app/.github/copilot-instructions.md

StarCitizenToolBox Flutter/Rust Desktop Application

StarCitizenToolBox is a Flutter desktop application with Rust native bindings designed for Star Citizen players. It provides localization management, game diagnostics, website translations, performance optimization, and various tools for the Star Citizen gaming experience. The app supports Windows, macOS, and Linux platforms using Fluent UI design.

Always reference these instructions first and fallback to additional search or context gathering only when information in these instructions is incomplete or found to be in error.

Working Effectively

Initial Setup and Dependencies

Install required dependencies in this exact order:

1. Install Rust toolchain:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
   source ~/.cargo/env
   

2. Install Flutter SDK (stable channel):

   # Clone Flutter repository
   cd /tmp
   git clone https://github.com/flutter/flutter.git -b stable --depth 1
   export PATH="/tmp/flutter/bin:$PATH"
   flutter --version
   

   Note: If Flutter download fails due to network issues, the build can still proceed with existing generated code.

3. Install essential Rust tools:

   cargo install cargo-expand
   cargo install 'flutter_rust_bridge_codegen@^2.0.0-dev.0'
   

Build Process - NEVER CANCEL LONG-RUNNING COMMANDS

Execute these commands in sequence. NEVER CANCEL - builds can take 45+ minutes:

1. Install Flutter dependencies: (2-3 minutes)

   flutter pub get
   

2. Generate Dart code: (3-5 minutes)

   dart run build_runner build --delete-conflicting-outputs
   

3. Update Rust dependencies: (10-15 minutes first time, 2-3 minutes subsequent)

   cd rust && cargo update
   

4. Generate Rust-Dart bridge code: (5-8 minutes)

   flutter_rust_bridge_codegen generate
   

5. Generate localization files: (1-2 minutes)

   flutter pub global activate intl_utils
   flutter pub global run intl_utils:generate
   

6. Build Rust components: (60-90 seconds debug, 110-120 seconds release)

   cd rust
   cargo build --release  # NEVER CANCEL: Takes ~2 minutes
   

7. Build Flutter application: (15-25 minutes - NEVER CANCEL)

   flutter build windows -v  # Set timeout to 30+ minutes minimum
   

CRITICAL BUILD TIMING:

• Complete full build from scratch: 45-60 minutes - NEVER CANCEL
• Rust release build: 2 minutes - NEVER CANCEL
• Flutter application build: 15-25 minutes - NEVER CANCEL
• Code generation steps: 10-15 minutes total - NEVER CANCEL

Platform-Specific Build Requirements

Windows (Primary Platform):

• MSBuild tools
• Visual Studio Build Tools or Visual Studio Community
• Windows SDK
• LLVM/Clang (version 18+ recommended)

Linux (Development/Testing):

• Basic build tools: build-essential, cmake, ninja-build
• GTK development libraries
• Limited functionality (desktop app designed primarily for Windows)

macOS:

• Xcode Command Line Tools
• CMake

Testing and Validation

Rust Component Testing:

cd rust
cargo check  # Fast syntax check (1-2 minutes)
cargo test   # Run Rust unit tests (5-10 minutes - NEVER CANCEL)

Flutter Testing:

flutter test  # Run Flutter widget tests (2-5 minutes)

Linting and Code Quality:

flutter analyze          # Dart/Flutter linting (30-60 seconds)
cd rust && cargo clippy  # Rust linting (2-3 minutes)

Manual Validation Requirements

After building, always perform these validation steps:

1. Verify application starts:

   # Windows
   ./build/windows/x64/runner/Release/starcitizen_doctor.exe
   
   # Linux (limited functionality)
   ./build/linux/x64/release/bundle/starcitizen_doctor
   

2. Test core functionality:

   • Application launches without crashes
   • Main navigation works
   • Settings panel accessible
   • Localization switching functional

Note: Full UI testing requires Windows environment. Linux builds have limited functionality.

Project Structure and Key Files

Entry Points and Main Code

• Main application: lib/main.dart - Flutter app entry point with multi-window support
• App configuration: lib/app.dart - Application state, routing, theming, and localization
• Rust bridge: lib/common/rust/ - Generated Rust-Dart interop code
• UI modules: lib/ui/ - All user interface components organized by feature

Build Configuration

• Flutter config: pubspec.yaml - Dependencies, assets, build settings
• Rust config: rust/Cargo.toml - Native dependencies and build settings
• Rust bridge: flutter_rust_bridge.yaml - Bridge code generation settings
• Analysis: analysis_options.yaml - Dart/Flutter linting rules

Build System Files

• Rust builder: rust_builder/ - Custom Rust compilation integration with cargokit
• Platform builds: windows/, linux/, macos/ - Platform-specific build configurations
• CI/CD: .github/workflows/windows_nightly.yml - Automated build pipeline

Generated Code (DO NOT EDIT)

• lib/generated/ - Auto-generated localization files
• lib/**/*.g.dart - Generated JSON serialization code
• lib/**/*.freezed.dart - Generated immutable data classes
• lib/common/rust/ - Generated Rust-Dart bridge code

Development Workflow

Making Changes

1. For Dart/Flutter changes:

   # After UI or logic changes
   dart run build_runner build --delete-conflicting-outputs
   flutter analyze
   

2. For Rust changes:

   cd rust
   cargo check  # Quick validation
   flutter_rust_bridge_codegen generate  # Regenerate bridge if API changed
   

3. For localization changes:

   flutter pub global run intl_utils:generate
   

Pre-commit Validation

Always run before committing changes:

flutter analyze                    # Dart linting (required for CI)
cd rust && cargo clippy           # Rust linting  
flutter test                      # Widget tests
cd rust && cargo test            # Rust tests

CI Pipeline will fail if:

• Flutter analyze reports errors
• Rust clippy reports errors
• Any tests fail
• Build process fails

Common Issues and Solutions

Flutter/Dart Issues

• Build runner conflicts: Delete generated files and rebuild with --delete-conflicting-outputs
• Dependency conflicts: Run flutter pub deps to check for version conflicts
• Localization missing: Ensure flutter pub global run intl_utils:generate completed successfully

Rust Issues

• Bridge generation fails: Verify flutter_rust_bridge_codegen is installed and Rust code compiles
• Link errors: Ensure all required system libraries are installed for target platform
• API changes: Regenerate bridge code after modifying Rust API signatures

Build Performance

• Use cargo check instead of cargo build for quick Rust validation
• Use flutter analyze instead of full build for quick Dart validation
• Clean build artifacts if experiencing issues: flutter clean && cd rust && cargo clean

Application Architecture

UI Framework: Flutter with Fluent UI design system for Windows-native appearance State Management: Riverpod with code generation for type-safe state management
Routing: GoRouter for navigation with nested routes Localization: Flutter i18n with custom tooling for community translations Data Layer: Hive for local storage, HTTP client for network requests Native Integration: Rust via flutter_rust_bridge for system operations and performance-critical code

Key Development Commands Reference

# Quick development validation (5-10 minutes total)
flutter analyze && cd rust && cargo check

# Full build validation (45-60 minutes - NEVER CANCEL)
flutter pub get && \
dart run build_runner build --delete-conflicting-outputs && \
cd rust && cargo update && cd .. && \
flutter_rust_bridge_codegen generate && \
flutter pub global run intl_utils:generate && \
flutter build windows -v

# Code generation only (5-10 minutes)
dart run build_runner build --delete-conflicting-outputs && \
flutter_rust_bridge_codegen generate && \
flutter pub global run intl_utils:generate

# Test execution (10-15 minutes total - NEVER CANCEL)
flutter test && cd rust && cargo test

CRITICAL REMINDERS:

• NEVER CANCEL builds or long-running commands - they can take 45+ minutes
• Always set command timeouts to 60+ minutes for build operations
• Always set command timeouts to 30+ minutes for test operations
• Validate changes with both quick checks and full builds before committing
• Use Windows environment for complete functionality testing