Copilot instructions

1# Copilot Instructions for `leoafarias/fvm`
2 
3## Project overview
4- FVM is a Dart CLI that manages Flutter SDK versions per project.
5- Main architecture flow: **Commands → Workflows → Services → Models**.
6- Key paths:
7  - `bin/main.dart` (CLI entrypoint)
8  - `lib/src/commands/` (command handlers)
9  - `lib/src/workflows/` (multi-step orchestration)
10  - `lib/src/services/` (core business logic)
11  - `lib/src/models/` (data models, many generated with `dart_mappable`)
12  - `test/` (unit + integration tests)
13 
14## First-run checklist for coding agents
151. Read `AGENTS.md` and `.context/docs/README.md`.
162. Install dependencies:
17   - Root: `dart pub get`
18   - Also check subprojects when touched:
19     - `fvm_mcp/`: `dart pub get`
20     - `tool/release_tool/`: `dart pub get` (requires Dart `>=3.8.0`)
213. Before changing code, run baseline checks (if environment supports Dart):
22   - `dart analyze --fatal-infos`
23   - `dcm analyze lib`
24   - `dart test`
254. After changes, re-run targeted checks first, then broader checks relevant to touched areas.
26 
27## Build, test, and analysis commands
28- Root project:
29  - `dart pub get`
30  - `dart analyze --fatal-infos`
31  - `dcm analyze lib`
32  - `dart test`
33- Integration suite (Flutter required):
34  - `dart run grinder test-setup`
35  - `dart run grinder integration-test`
36- Mapper/codegen (required after editing `@MappableClass()` models):
37  - `dart run build_runner build --delete-conflicting-outputs`
38 
39## Repository-specific conventions
40- Keep changes surgical: avoid broad refactors unless required by the issue.
41- Prefer existing testing utilities (`TestFactory`, `TestCommandRunner`) and patterns in `.context/docs/testing-methodology.md`.
42- Integration tests are heavyweight and network-sensitive; prefer unit/targeted tests first.
43- Release tooling is separate under `tool/release_tool/` and uses a newer Dart SDK than the main repo.
44 
45## CI and workflow context
46- Main validation workflow: `.github/workflows/test.yml`.
47- `test.yml` ignores docs-only changes (`**/*.md`), so editing this file alone should not trigger the heavy test workflow.
48- CI includes fallback install logic for DCM:
49  - If `dcm` is unavailable, run `dart pub global activate dart_code_metrics` and add `$HOME/.pub-cache/bin` to `PATH`.
50 
51## Errors encountered during onboarding and workarounds
521. **Local command failure**: `dart: command not found`
53   - Seen when running `dart pub get`, `dart analyze --fatal-infos`, and `dart test` in this environment.
54   - Workaround: install/setup Dart before validation (CI uses `dart-lang/setup-dart`; locally ensure `dart --version` works, then rerun commands).
552. **GitHub Actions log retrieval limitation for a failed run**:
56   - `get_workflow_run_logs_url` returned `404 Not Found`.
57   - `list_workflow_jobs`/`get_job_logs` returned zero jobs for that run.
58   - Workaround: inspect `get_workflow_run` metadata (run URL, branch, event) and use the Actions UI/run page for details when API log endpoints are unavailable.
59 
60## High-value docs for deeper context
61- `README.md` (project/release overview)
62- `.github/workflows/README.md` (deployment/CI details)
63- `.context/docs/testing-methodology.md`
64- `.context/docs/integration-tests.md`
65- `.context/docs/version-parsing.md`
66- `.context/docs/v4-release-notes.md`
67