# 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 launcher is responsible for:

- logging in to a player's MoonWell account
- downloading and synchronizing client files
- displaying launcher news
- 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 `fvm flutter --version`.

## Configuration

Set the launcher Web API base URL at compile time:

```powershell
--dart-define=MOONWELL_API_BASE_URL=https://host
```

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

```powershell
--dart-define=MOONWELL_APPCAST_URL=https://host/launcher/updates/appcast.xml
```

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

Example run command:

```powershell
fvm flutter run -d windows --dart-define=MOONWELL_API_BASE_URL=https://host --dart-define=MOONWELL_APPCAST_URL=https://host/launcher/updates/appcast.xml
```

## Development

Run the component catalog from its standalone workspace:

```powershell
cd widgetbook
fvm dart run build_runner build
fvm 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
fvm dart run build_runner build --delete-conflicting-outputs
```

Run static analysis:

```powershell
fvm flutter analyze
```

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

Build the Windows launcher:

```powershell
fvm flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://host --dart-define=MOONWELL_APPCAST_URL=https://host/launcher/updates/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.

## 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
3. scan the selected installation directory
4. compare local files to the manifest
5. remove stale files outside ignored directories
6. download missing or changed files to temporary part files
7. verify size and SHA-256 before replacing client files
8. 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/widgetbook.md`: Widgetbook use-case generation and catalog conventions