# 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`.

Launcher version labels are read from the packaged application metadata. Change
only the `version: X.Y.Z+N` value in `pubspec.yaml`; login, launcher status,
Windows metadata, installer packaging, and AppCast are synchronized from it.

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.

```powershell
fvm flutter pub get
```

Verify the configured SDK with `flutter --version`.

## Configuration

Set the launcher Web API base URL at compile time:

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

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

```powershell
--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:

```powershell
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:

```powershell
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:

```powershell
dart run build_runner build --delete-conflicting-outputs
```

Run static analysis:

```powershell
flutter analyze
```

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

Build the Windows launcher:

```powershell
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:

```powershell
.\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