moonwell-launcher/docs/project_review.md

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.