From 0363e915ee2f627bc4708a62faab44f58e7c0ce1 Mon Sep 17 00:00:00 2001 From: gasaichandesu Date: Thu, 18 Jun 2026 23:51:07 +0400 Subject: [PATCH] docs: Add basic AI guidelines and documentation --- AGENTS.md | 92 ++++++++++++++++++++++++++++++++++++ README.md | 104 ++++++++++++++++++++++++++++++++++++---- docs/linting.md | 42 +++++++++++++++++ docs/project_review.md | 105 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 333 insertions(+), 10 deletions(-) create mode 100644 AGENTS.md create mode 100644 docs/linting.md create mode 100644 docs/project_review.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7db9200 --- /dev/null +++ b/AGENTS.md @@ -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. diff --git a/README.md b/README.md index f1748b2..a0ab40a 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/linting.md b/docs/linting.md new file mode 100644 index 0000000..f41de17 --- /dev/null +++ b/docs/linting.md @@ -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. diff --git a/docs/project_review.md b/docs/project_review.md new file mode 100644 index 0000000..608d927 --- /dev/null +++ b/docs/project_review.md @@ -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.