moonwell-launcher/README.md

MoonWell Launcher

MoonWell Launcher is the desktop launcher for MoonWell, a private World of Warcraft: Wrath of the Lich King server focused on a player-friendly experience without excessive grind and with stronger social play.

The Windows executable requests administrator privileges on startup so it can synchronize game clients installed under protected directories such as Program Files.

The launcher is responsible for:

• logging in to a player's MoonWell account
• registering new MoonWell game accounts
• downloading and synchronizing client files
• displaying launcher news
• displaying the live status of the first configured realm
• launching the game client

Stack

• Flutter desktop
• Dart
• flutter_bloc for launcher UI state
• get_it and injectable for dependency injection
• dio for Web API and file download requests
• flutter_secure_storage for launcher sessions
• shared_preferences for non-sensitive launcher preferences

Prerequisites

Install FVM. The repository .fvmrc tracks the latest stable Flutter channel, and all Dart and Flutter commands are run through FVM.

fvm flutter pub get

Verify the configured SDK with flutter --version.

Configuration

Set the launcher Web API base URL at compile time:

--dart-define=MOONWELL_API_BASE_URL=https://moon-well.online

Set the public AppCast feed URL to enable Windows launcher self-updates:

--dart-define=MOONWELL_APPCAST_URL=https://moon-well.online/appcast.xml

The updater is disabled when MOONWELL_APPCAST_URL is omitted. Production feeds must use HTTPS.

Example run command:

flutter run -d windows --dart-define=MOONWELL_API_BASE_URL=https://moon-well.online --dart-define=MOONWELL_APPCAST_URL=https://moon-well.online/appcast.xml

Development

Run the component catalog from its standalone workspace:

cd widgetbook
dart run build_runner build
flutter run -d windows

See docs/widgetbook.md for the required use-case naming, knobs, callback, asset, and coverage conventions.

Regenerate dependency injection after changing injectable services:

dart run build_runner build --delete-conflicting-outputs

Run static analysis:

flutter analyze

See docs/linting.md for the full format, analyze, test, and Lefthook pre-commit workflow.

Build the Windows launcher:

flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://moon-well.online --dart-define=MOONWELL_APPCAST_URL=https://moon-well.online/appcast.xml

The Inno Setup installer script lives at installer/moonwell_launcher.iss. See docs/launcher_self_update.md for the AppCast format, signing keys, and manual release procedure.

Run a safe local production-release rehearsal:

.\tool\deploy_launcher.ps1 `
  -DryRun `
  -ExpectedVersion 1.0.2 `
  -ReleaseNotes "Исправления и улучшения MoonWell Launcher."

Remove -DryRun only after reviewing the generated installer and AppCast. See docs/production_deploy.md for required environment variables, production defaults, safety checks, and failure recovery.

Local deploy credentials are read from the ignored root .env; use .env.example as the safe template. Process and CI environment variables override values from the file.

Architecture

The UI lives in lib/app. Presentation-only design-system components live in lib/app/design_system and are catalogued by the standalone widgetbook/ workspace before they are integrated into production screens. Launcher domain models, sync use cases, API clients, installation services, and preferences live under lib/features.

The launcher sync flow is manifest-based:

1. authenticate against the MoonWell Web API
2. fetch the client manifest and automatically synchronize a saved client installation
3. refresh the manifest every five minutes while the launcher is open and automatically synchronize when the server build changes
4. scan the selected installation directory
5. compare local files to the manifest
6. remove stale files outside ignored directories
7. download missing or changed files to temporary part files
8. verify size and SHA-256 before replacing client files
9. launch Wow.exe from the selected client directory

See docs/launcher_web_api_spec.md for the API and sync contract.

Documentation

• AGENTS.md: architecture, commands, and repository rules for contributors
• TODO.md: remaining verification and maintenance tasks
• docs/linting.md: format, analyze, test, and Lefthook workflow
• docs/project_review.md: project review with strengths, weaknesses, and upgrade feasibility notes
• docs/launcher_web_api_spec.md: current launcher Web API and sync behavior
• docs/launcher_self_update.md: Windows self-update and release operations
• docs/production_deploy.md: automated production launcher deployment
• docs/widgetbook.md: Widgetbook use-case generation and catalog conventions