From da2eeee5189df46d860be3d7e2d5ade0e8363403 Mon Sep 17 00:00:00 2001 From: Tommy Chow Date: Sun, 11 Jan 2026 04:26:05 -0800 Subject: [PATCH] update claude and copilot instructions for accuracy - fix global stores documentation (add GlobalAssetsStore location, remove UserStore) - correct error handling docs (typed exceptions via BaseApiClient, not Future.error) - add missing lint rules (avoid_redundant_argument_values, unnecessary_parenthesis) - fix emote factory methods (add all 4: fromTwitch, fromBTTV, fromFFZ, from7TV) - update build_runner commands to modern dart run syntax - add MobX reactions examples and API architecture section - align commit convention with actual repo style (lowercase, no prefixes) Co-Authored-By: Claude Opus 4.5 --- .github/copilot-instructions.md | 24 ++++-- CLAUDE.md | 131 +++++++++++--------------------- 2 files changed, 61 insertions(+), 94 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 520fe380..744582f7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -15,19 +15,20 @@ Frosty is a cross-platform Flutter app for Twitch that supports third-party emot - `flutter build apk` - Build Android APK - `flutter build ios` - Build iOS app - `flutter analyze` - Run static analysis and lint checks +- `flutter test` - Run all tests ### Code Generation (REQUIRED) All MobX stores and JSON models require code generation. **Always run after any MobX or model changes:** ```bash -flutter packages pub run build_runner build --delete-conflicting-outputs +dart run build_runner build --delete-conflicting-outputs ``` **Alternative commands:** -- `flutter packages pub run build_runner build` - Generate code once -- `flutter packages pub run build_runner watch` - Watch and regenerate code on changes +- `dart run build_runner build` - Generate code once +- `dart run build_runner watch` - Watch and regenerate code on changes Generated `.g.dart` files are excluded from linting but must be committed to source control. @@ -45,7 +46,9 @@ flutter run --dart-define=clientId=YOUR_TWITCH_CLIENT_ID --dart-define=secret=YO - **Store Pattern**: Each feature has stores in `lib/screens/{feature}/stores/` (not at screen root) - **Naming**: All stores end with `Store` suffix and have corresponding `.g.dart` files -- **Global Stores**: `AuthStore` and `SettingsStore` in `lib/screens/settings/stores/` +- **Global Stores**: + - `AuthStore`, `SettingsStore` in `lib/screens/settings/stores/` + - `GlobalAssetsStore` (shared emote/badge cache) in `lib/stores/` - **Dependency Injection**: Stores are provided via Provider in `main.dart` with shared HTTP client ### API Service Architecture @@ -97,7 +100,7 @@ lib/screens/{feature}/ ### Model Generation - **JSON Serialization**: Models use `@JsonSerializable()` with `.g.dart` companions -- **Emote Architecture**: Base `Emote` class with platform-specific factories (`Emote.fromTwitch()`, `Emote.fromBTTV()`) +- **Emote Architecture**: Base `Emote` class with platform-specific factories (`Emote.fromTwitch()`, `Emote.fromBTTV()`, `Emote.fromFFZ()`, `Emote.from7TV()`) ## Key Integration Points @@ -140,7 +143,7 @@ Analysis rules in `analysis_options.yaml`: - Package imports: `always_use_package_imports` - Trailing commas: `require_trailing_commas` - Final locals: `prefer_final_locals` -- Additional rules: `directives_ordering`, `avoid_void_async`, `always_declare_return_types` +- Additional rules: `directives_ordering`, `avoid_void_async`, `always_declare_return_types`, `avoid_redundant_argument_values`, `unnecessary_parenthesis` **Important**: `.g.dart` files are excluded from analysis but must be committed to source control. @@ -166,7 +169,8 @@ autorun((_) => prefs.setString('settings', jsonEncode(settingsStore))); ### Error Handling -Use `Future.error()` for API failures, not exceptions. +API services use typed exceptions via `BaseApiClient` (`lib/apis/base_api_client.dart`): +- `ApiException`, `NetworkException`, `TimeoutException`, `ServerException`, `NotFoundException`, `UnauthorizedException` ## MobX Store Implementation @@ -174,7 +178,7 @@ Use `Future.error()` for API failures, not exceptions. All stores follow `StoreBase with _$StoreName` pattern: -- Generate `.g.dart` files with `flutter packages pub run build_runner build` +- Generate `.g.dart` files with `dart run build_runner build` - Use `@observable`, `@action`, and `@computed` annotations - Settings store uses `@JsonSerializable()` with automatic persistence via `autorun()` @@ -205,4 +209,8 @@ Settings automatically saved to SharedPreferences via MobX `autorun()` reaction. - **Custom Cache**: `CustomCacheManager` for media caching - **PiP Mode**: Custom implementation via git dependency +## Commit Convention + +Commits use lowercase, descriptive messages without prefixes (e.g., `fix landscape bottom padding in chat bottom bar`, `add swipe pip gesture support`). Keep commits tightly scoped. + When working with this codebase, always consider MobX code generation requirements and the shared HTTP client pattern for API efficiency. diff --git a/CLAUDE.md b/CLAUDE.md index 40caf127..b9d22e4e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,74 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Development Workflow -**Plan Mode - In-Depth Planning**: When in plan mode, interview thoroughly before coding: - +**Plan Mode**: When in plan mode, interview thoroughly before coding: - Ask detailed questions about technical implementation, UI/UX concerns, tradeoffs, and edge cases - Continue asking questions until all requirements and non-obvious decisions are clear - Don't begin implementation until all important details are resolved **Pattern Consistency**: When implementing new code: - - Search the codebase to find existing usages and implementations - Prefer following established patterns, styles, and practices for consistency -## Skills & Plugins - -Claude Code has access to specialized skills. Use them proactively based on context: - -**`/feature-dev:feature-dev`** — Guided Feature Development -- Use when: Planning or implementing new features, analyzing architecture, creating implementation blueprints -- Trigger phrases: "add a feature", "implement", "build", "create new functionality" - -**`/frontend-design:frontend-design`** — Production UI Components -- Use when: Creating or improving UI components, widgets, screens, or visual design -- Trigger phrases: "design", "build UI", "create a widget", "improve the interface" - -**`/code-review:code-review`** — Code Quality Review -- Use when: After writing or modifying code, before commits, reviewing changes -- Trigger phrases: "review my code", "check this", "is this good?" -- **Proactive**: Suggest after significant code modifications - -**`/pr-review-toolkit:review-pr`** — Comprehensive PR Review -- Use when: Before creating PRs, reviewing PR changes, final quality checks -- Trigger phrases: "review the PR", "check before merging", "PR ready?" - -### Automatic Triggers - -Claude should proactively suggest skills in these situations: - -| After This Action | Suggest This Skill | -|-------------------|-------------------| -| Writing/editing multiple files | `/code-review:code-review` | -| Completing a feature implementation | `/code-review:code-review` | -| User says "ready for PR" or "create PR" | `/pr-review-toolkit:review-pr` | -| Discussing new feature requirements | `/feature-dev:feature-dev` | -| Building UI components or screens | `/frontend-design:frontend-design` | - -### Specialized Subagents - -These are advanced capabilities Claude can use for deeper analysis (not slash commands, but can be requested): - -**Code Quality & Review:** -- **Silent Failure Hunter** — Finds silent failures, poor error handling, swallowed exceptions - - Trigger: "hunt for silent failures", "check error handling", "find swallowed errors" -- **Code Simplifier** — Simplifies code while preserving functionality - - Trigger: "simplify this code", "make this cleaner", "reduce complexity" -- **Comment Analyzer** — Checks comments for accuracy and technical debt - - Trigger: "review the comments", "check documentation accuracy" - -**Architecture & Types:** -- **Type Design Analyzer** — Analyzes type design, encapsulation, and invariants - - Trigger: "analyze type design", "review this type", "check encapsulation" -- **Code Architect** — Designs feature architectures with implementation blueprints - - Trigger: "design the architecture", "create implementation blueprint" -- **Code Explorer** — Deep analysis of existing features, traces execution paths - - Trigger: "trace this flow", "how does this work end-to-end", "analyze this feature" - -**Testing:** -- **PR Test Analyzer** — Reviews test coverage quality and identifies gaps - - Trigger: "analyze test coverage", "are tests thorough enough", "find test gaps" - ## Development Commands **Common Commands:** @@ -82,9 +23,9 @@ These are advanced capabilities Claude can use for deeper analysis (not slash co - `flutter build apk` / `flutter build ios` - Build release binaries **Code Generation** (required after changing MobX stores or `@JsonSerializable` models): -- `flutter packages pub run build_runner build` - Generate once -- `flutter packages pub run build_runner build --delete-conflicting-outputs` - Force rebuild all -- `flutter packages pub run build_runner watch` - Watch mode for development +- `dart run build_runner build` - Generate once +- `dart run build_runner build --delete-conflicting-outputs` - Force rebuild all +- `dart run build_runner watch` - Watch mode for development ## Architecture Overview @@ -106,11 +47,11 @@ These are advanced capabilities Claude can use for deeper analysis (not slash co 3. Settings persisted via `SettingsStore` with SharedPreferences and MobX `autorun()` 4. API services share a common Dio HTTP client for efficient connection reuse -**Global Stores** (provided at app root in `main.dart`): +**Global Stores** (injected via Provider in `main.dart`): -- `AuthStore` - Authentication state and token management -- `SettingsStore` - User preferences with automatic persistence via MobX `autorun()` -- `GlobalAssetsStore` - Shared cache for global emotes and badges across all chat tabs +- `AuthStore` (`lib/screens/settings/stores/`) - Authentication state and token management +- `SettingsStore` (`lib/screens/settings/stores/`) - User preferences with automatic persistence via MobX `autorun()` +- `GlobalAssetsStore` (`lib/stores/`) - Shared cache for global emotes and badges across all chat tabs **HTTP & Auth**: Centralized Dio client (`DioClient.createClient()`) with connection pooling and optimized timeouts. `TwitchAuthInterceptor` auto-injects auth headers for Twitch API URLs. `UnauthorizedInterceptor` catches 401 errors for token refresh. Two-tier token system: default app token + optional user token in Flutter Secure Storage. @@ -133,37 +74,55 @@ abstract class SomeStoreBase with Store { } ``` -After any changes to MobX stores or `@JsonSerializable()` models, run the build_runner to regenerate `.g.dart` files. +**MobX Reactions** (for side effects and persistence): + +```dart +// Auto-save settings whenever they change (in main.dart) +autorun((_) => prefs.setString('settings', jsonEncode(settingsStore))); + +// React to specific state changes +reaction((_) => authStore.isLoggedIn, (_) => _selectedIndex = 0); +``` ## Chat System Architecture - **Real-time IRC**: WebSocket connection to Twitch IRC with custom `IRCMessage` parsing - **Third-party Emotes**: Asynchronous loading of BTTV, FFZ, and 7TV assets via dedicated APIs - **Message Management**: 5000 message limit with 20% batch removal optimization -- **Assets Store**: Separate `ChatAssetsStore` manages channel-specific emotes/badges; `GlobalAssetsStore` caches global assets +- **Assets Store**: `ChatAssetsStore` manages channel-specific emotes/badges -## Deep Linking +## Additional Patterns -App supports Twitch channel deep links (e.g., `twitch.tv/channelname`). Deep link handling in `main.dart`: -- Uses `app_links` package for URI stream handling -- Resolves channel names via Twitch API before navigation -- Graceful fallback with in-app browser option on failure +**Emote Architecture**: Base `Emote` class with platform-specific factories: `Emote.fromTwitch()`, `Emote.fromBTTV()`, `Emote.fromFFZ()`, `Emote.from7TV()`. + +**Custom Cache Manager**: Uses 30-day stale period and 10k max objects. `CustomCacheManager.removeOrphanedCacheFiles()` runs on startup to clean files not in database. + +**Secure Storage Cleanup**: First-run detection clears Flutter Secure Storage to handle Android/iOS uninstall edge case where secure storage persists but app data is wiped. + +## API Architecture + +**BaseApiClient Pattern**: All API services (`TwitchApi`, `BTTVApi`, `FFZApi`, `SevenTVApi`) extend `BaseApiClient` which provides: +- Generic GET/POST/PUT/DELETE methods with centralized error handling +- Automatic conversion of `DioException` to typed exceptions + +**Exception Hierarchy** (in `lib/apis/base_api_client.dart`): +- `ApiException` - Base class for all API errors +- `NetworkException` - Connection errors (no internet) +- `TimeoutException` - Request timeouts +- `ServerException` - 5xx server errors +- `NotFoundException` - 404 errors +- `UnauthorizedException` - 401 errors (triggers token refresh) ## Code Style -Analysis rules enforced via `analysis_options.yaml`: +**Lint Rules** (from `analysis_options.yaml`): +- `prefer_single_quotes`, `always_use_package_imports`, `require_trailing_commas` +- `prefer_final_locals`, `prefer_final_in_for_each`, `avoid_redundant_argument_values` +- `directives_ordering`, `avoid_void_async`, `always_declare_return_types`, `unnecessary_parenthesis` -- `prefer_single_quotes` - Use single quotes for strings -- `always_use_package_imports` - Package imports over relative imports -- `require_trailing_commas` - Trailing commas on multi-line constructs -- `prefer_final_locals`, `prefer_final_in_for_each` - Prefer final variables -- `directives_ordering`, `avoid_void_async`, `always_declare_return_types` -- `avoid_redundant_argument_values`, `unnecessary_parenthesis` - -Generated `.g.dart` files are excluded from analysis but must be committed. - -**Error Handling**: Use `Future.error()` for API failures rather than throwing exceptions. +**Other**: +- Generated `.g.dart` files must be committed alongside source changes ## Commit Convention -Commits follow conventional format: `refactor:`, `feat:`, `fix:`, `format:`, etc. Keep commits tightly scoped. Include generated `.g.dart` outputs in the same commit as their source changes. +Commits use lowercase, descriptive messages without prefixes (e.g., `fix landscape bottom padding in chat bottom bar`, `add swipe pip gesture support`). Keep commits tightly scoped.