# MoonWell Launcher Project Review

Reviewed on 2026-06-18.

## Overview

MoonWell Launcher is a Flutter desktop application for a private World of
Warcraft: Wrath of the Lich King server. Its core responsibilities are account
login, client installation/synchronization, news display, and launching
`Wow.exe`.

The project is already more than a Flutter template: it has a clear launcher
API contract, domain models for manifests and sessions, a sync use case,
installation scanning, logging, dependency injection, and tests around the
most important file verification behavior.

## Strong Points

- The project uses a readable layered structure: UI under `lib/app`, feature
  code under `lib/features`, and shared primitives under `lib/core`.
- Client sync is manifest driven and verifies downloaded files by size and
  SHA-256 before replacing local files.
- Local path handling normalizes manifest paths and rejects absolute paths or
  traversal attempts before resolving files under the selected installation
  directory.
- Player-generated or volatile client directories are excluded from
  verification: `Cache`, `Errors`, `Logs`, `Screenshots`, `WTF`, and launcher
  metadata.
- Hash caching is implemented as an optimization while keeping the server
  manifest as the source of truth.
- Sync diagnostics are written to `.moonwell_launcher/launcher.log`, and failed
  downloads can be preserved for inspection.
- The Web API integration is documented in `docs/launcher_web_api_spec.md`,
  including login, manifest, presigned download, news, pause/resume, and launch
  behavior.
- Tests cover deterministic build hash behavior, ignored directories, hash
  cache behavior, path traversal rejection, sync success, stale file removal,
  download verification failure, session restore, preferences, and news loading.

## Weak Points And Risks

- `README.md` was still the generated Flutter starter text before this review,
  so new contributors had no project-specific setup or operation guide.
- There was no `AGENTS.md`, so future automated or human contributors had to
  infer architecture, commands, and safety rules from source code.
- At initial review, `lib/main.dart` contained a large inactive demo
  `LauncherHome` implementation. This has since been removed from the active
  entrypoint.
- At initial review, several Russian UI strings appeared mojibake-encoded in
  the active login and home flow. These active strings have since been
  normalized to UTF-8.
- At initial review, custom title-bar widgets were duplicated between login and
  home screens. They have since been extracted into a shared widget.
- Session tokens were originally persisted through `shared_preferences`. They
  now use `flutter_secure_storage`, while `shared_preferences` remains limited
  to non-sensitive launcher preferences.
- The dependency injection output file `lib/service_container.config.dart` is
  committed, but the regeneration command was not previously documented.
- UI/widget/integration coverage is still light compared with the risk in login,
  bootstrap, directory selection, news failure handling, sync controls, and
  launch behavior.
- There is no visible CI configuration in the repository.
- The current working tree already had modified `pubspec.yaml` and
  `pubspec.lock` before this documentation pass. Those changes were not part of
  this review and should be preserved.

## Flutter 3.44.2 Upgrade Feasibility

Assumption: `3.44.2` means Flutter SDK `3.44.2`.

Current local indicators:

- `.fvmrc` is absent.
- `pubspec.yaml` declares Dart SDK `^3.9.0`.
- `pubspec.lock` declares Flutter SDK `>=3.38.0`.
- The project policy is latest stable Flutter SDK only; FVM-pinned workflows are
  not supported.
- The local shell now finds Flutter `3.44.2` on the stable channel.

Flutter `3.44.2` has been validated for dependency resolution, formatting,
analysis, and tests. A production-like Windows build smoke test remains open.

Recommended upgrade path:

1. Keep the latest stable Flutter SDK on PATH.
2. Run `flutter pub get`.
3. Regenerate dependency injection only if dependency resolution or generator
   output requires it:
   `dart run build_runner build --delete-conflicting-outputs`.
4. Run `flutter analyze`.
5. Run a Windows build smoke test:
   `flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://host`.

## Recommended Refactoring Direction

- Keep secure session persistence covered by tests when login or session
  restore behavior changes.
- Add CI or a documented local verification workflow that runs analysis and a
  Windows build smoke test with the latest stable Flutter SDK.