AGENTS.md

This file is the working guide for people and agents changing MoonWell Launcher. Keep it current when architecture, commands, or repository rules change.

Project Shape

MoonWell Launcher is a Flutter desktop app for a private World of Warcraft: Wrath of the Lich King server. It logs players in, downloads and synchronizes client files, displays launcher news, and starts Wow.exe.

Important areas:

lib/main.dart initializes Flutter, the desktop window, dependency injection, and MoonWellApp.
lib/app contains UI screens, BLoC state, widgets, and theme code.
lib/app/widgets contains shared app-level UI such as the custom desktop title bar.
lib/features/launcher/domain contains launcher entities such as sessions, manifests, news items, sync status, and exceptions.
lib/features/launcher/application contains use cases for session restore and client synchronization.
lib/features/launcher/data contains API, installation, and log services.
lib/features/preferences stores selected install directory and launcher session data.
lib/service_container.dart and lib/service_container.config.dart provide get_it/injectable dependency wiring.
docs/launcher_web_api_spec.md documents the current launcher Web API and sync behavior.

Flutter SDK Policy

MoonWell Launcher supports the latest stable Flutter SDK only. Do not introduce or rely on FVM-pinned workflows.

If flutter is not available after installing or updating Flutter, restart the shell and verify PATH with flutter --version.

Common Commands

flutter pub get
dart run build_runner build --delete-conflicting-outputs
dart format --set-exit-if-changed .
flutter analyze
flutter test
flutter run -d windows --dart-define=MOONWELL_API_BASE_URL=https://host
flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://host

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

In the current shell on 2026-06-18, flutter was not recognized by Get-Command flutter or where.exe flutter.

Configuration

The launcher API base URL is compile-time configuration:

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

Do not commit private credentials, production secrets, temporary bearer tokens, or local-only API URLs.

Architecture Notes

All backend calls should go through LauncherApiClient.
File sync behavior should stay in ClientSyncUseCase and GameInstallationService.
The server manifest is the source of truth for client files.
Downloads must write to *.moonwell.part, verify size and SHA-256, then replace the destination file only after successful verification.
Local scans should ignore volatile client directories and launcher metadata: Cache, Errors, Logs, Screenshots, WTF, and .moonwell_launcher.
Path normalization and traversal checks are safety-critical. Do not bypass GameInstallationService.resolveClientPath for manifest-relative paths.
lib/service_container.config.dart is generated by injectable. Do not hand-edit it unless you are intentionally repairing generated output; prefer regenerating it with build_runner.

Repository Rules

Preserve unrelated work in a dirty tree. This repository currently may have user edits in dependency files.
Keep changes scoped to the requested behavior.
Always keep README.md and files under docs/ up-to-date with any architecture, setup, API, sync, build, or operational change.
Keep documentation links current when files move.

3.5 KiB Raw Blame History