docs: Add basic AI guidelines and documentation
This commit is contained in:
gasaichandesu
@@ -0,0 +1,92 @@
|
||||
# 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
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```powershell
|
||||
--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.
|
||||
@@ -1,16 +1,100 @@
|
||||
# moonwell_launcher
|
||||
# MoonWell Launcher
|
||||
|
||||
A new Flutter project.
|
||||
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.
|
||||
|
||||
## Getting Started
|
||||
The launcher is responsible for:
|
||||
|
||||
This project is a starting point for a Flutter application.
|
||||
- logging in to a player's MoonWell account
|
||||
- downloading and synchronizing client files
|
||||
- displaying launcher news
|
||||
- launching the game client
|
||||
|
||||
A few resources to get you started if this is your first Flutter project:
|
||||
## Stack
|
||||
|
||||
- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
|
||||
- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
|
||||
- Flutter desktop
|
||||
- Dart
|
||||
- `flutter_bloc` for launcher UI state
|
||||
- `get_it` and `injectable` for dependency injection
|
||||
- `dio` for Web API and file download requests
|
||||
- `shared_preferences` for launcher preferences
|
||||
|
||||
For help getting started with Flutter development, view the
|
||||
[online documentation](https://docs.flutter.dev/), which offers tutorials,
|
||||
samples, guidance on mobile development, and a full API reference.
|
||||
## Prerequisites
|
||||
|
||||
Use the latest stable Flutter SDK available from the official Flutter release
|
||||
channel. This project does not support FVM-pinned SDK workflows.
|
||||
|
||||
```powershell
|
||||
flutter pub get
|
||||
```
|
||||
|
||||
If `flutter` is unavailable, restart the shell after installing Flutter or
|
||||
fix PATH so `flutter --version` works.
|
||||
|
||||
## Configuration
|
||||
|
||||
Set the launcher Web API base URL at compile time:
|
||||
|
||||
```powershell
|
||||
--dart-define=MOONWELL_API_BASE_URL=https://host
|
||||
```
|
||||
|
||||
Example run command:
|
||||
|
||||
```powershell
|
||||
flutter run -d windows --dart-define=MOONWELL_API_BASE_URL=https://host
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
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://host
|
||||
```
|
||||
|
||||
The Inno Setup installer script lives at `installer/moonwell_launcher.iss`.
|
||||
|
||||
## Architecture
|
||||
|
||||
The UI lives in `lib/app`, with shared UI widgets under `lib/app/widgets`.
|
||||
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`: refactoring, verification, and Flutter upgrade 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
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# Linting And Test Flow
|
||||
|
||||
MoonWell Launcher supports the latest stable Flutter SDK only. Do not use FVM
|
||||
for this project.
|
||||
|
||||
## Required Checks
|
||||
|
||||
Run these commands before committing:
|
||||
|
||||
```powershell
|
||||
dart format --set-exit-if-changed .
|
||||
flutter analyze
|
||||
flutter test
|
||||
```
|
||||
|
||||
Use `dart format .` to apply formatting fixes when the format check fails.
|
||||
|
||||
## Lefthook
|
||||
|
||||
This repository includes `lefthook.yml` with a `pre-commit` hook that runs the
|
||||
same format, analyze, and test flow.
|
||||
|
||||
Install Lefthook once on your machine, then install the Git hook from the repo
|
||||
root:
|
||||
|
||||
```powershell
|
||||
lefthook install
|
||||
```
|
||||
|
||||
Run the pre-commit flow manually with:
|
||||
|
||||
```powershell
|
||||
lefthook run pre-commit
|
||||
```
|
||||
|
||||
If `lefthook` is not available, install it with your preferred package manager
|
||||
from the official Lefthook distribution, then rerun `lefthook install`.
|
||||
|
||||
## Windows Troubleshooting
|
||||
|
||||
If Flutter reports that building with plugins requires symlink support, enable
|
||||
Windows Developer Mode and rerun the command.
|
||||
@@ -0,0 +1,105 @@
|
||||
# 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 are persisted through `shared_preferences`. That is simple and
|
||||
testable, but it is not hardened storage for bearer tokens.
|
||||
- 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` pins Flutter `3.35.2`.
|
||||
- `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 cannot find `flutter`: both `Get-Command flutter` and
|
||||
`where.exe flutter` fail.
|
||||
|
||||
Because `flutter` is not available in this shell, the upgrade cannot be fully
|
||||
validated here. If Flutter is installed, restart the shell or fix PATH so
|
||||
`flutter --version` works. The code and lockfile already suggest that the
|
||||
project has moved beyond the stale `.fvmrc` pin, so the upgrade is plausible,
|
||||
but it remains a tooling validation task.
|
||||
|
||||
Recommended upgrade path:
|
||||
|
||||
1. Install or expose the latest stable Flutter SDK on PATH.
|
||||
2. Confirm whether the latest stable Flutter SDK is `3.44.2` or newer.
|
||||
3. Remove or ignore stale FVM pinning if it conflicts with the latest-SDK
|
||||
policy.
|
||||
4. Run `flutter pub get`.
|
||||
5. Regenerate dependency injection only if dependency resolution or generator
|
||||
output requires it:
|
||||
`dart run build_runner build --delete-conflicting-outputs`.
|
||||
6. Run `flutter analyze`.
|
||||
7. Run a Windows build smoke test:
|
||||
`flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://host`.
|
||||
|
||||
## Recommended Refactoring Direction
|
||||
|
||||
- Decide whether bearer tokens can remain in `shared_preferences`; if not,
|
||||
migrate session storage to platform-secure storage.
|
||||
- Add CI or a documented local verification workflow that runs analysis and a
|
||||
Windows build smoke test with the latest stable Flutter SDK.
|
||||
Reference in New Issue
Block a user