AGENTS.md

1# FVM - Flutter Version Manager
2 
3CLI tool for managing Flutter SDK versions per project.
4 
5## Structure
6 
7- `bin/main.dart`: CLI entry point
8- `lib/src/commands/`: CLI commands
9- `lib/src/services/`: Business logic (cache, flutter, git, project)
10- `lib/src/workflows/`: Multi-step orchestration
11- `lib/src/models/`: Data models (dart_mappable)
12- `test/`: Unit + integration tests
13 
14## Commands
15 
16```bash
17dart pub get                    # Install dependencies
18dart test                       # Unit tests
19dart run grinder integration-test  # Integration suite (needs Flutter)
20dart analyze --fatal-infos      # Analysis (must pass)
21dcm analyze lib                 # Code metrics
22dart run build_runner build --delete-conflicting-outputs  # Regenerate mappers
23```
24 
25## Verification
26 
27Pre-commit hooks run automatically. Before pushing:
281. `dart analyze --fatal-infos` passes
292. `dcm analyze lib` passes
303. `dart test` passes
31 
32For final review on changes that affect `GitService`, `FlutterService`,
33`EnsureCacheWorkflow`, install/use/global command behavior, prompt handling, or
34project SDK references, also run the manual branch smoke test in
35`docs/pages/documentation/guides/manual-smoke-test.md`. It uses isolated temp `HOME`,
36`FVM_CACHE_PATH`, and `FVM_GIT_CACHE_PATH` values and includes cleanup guidance
37for the temporary SDKs, git cache, project files, and config it creates.
38 
39## Architecture
40 
41Commands → Workflows → Services → Models
42 
43- Services accessed via `FvmContext.get<T>()`
44- Workflows extend `Workflow` for multi-step operations
45- Models use `@MappableClass()` with `part 'name.mapper.dart';`
46 
47## Critical Rules
48 
49- NEVER bypass git hooks with `--no-verify`
50- YOU MUST run `build_runner build` after modifying `@MappableClass()` models
51- Integration tests require Flutter: run `dart run grinder test-setup` first
52 
53## Gotchas
54 
55- Release tool (`tool/release_tool/`) requires Dart >=3.8.0
56- Version format: `[fork/]version[@channel]` (e.g., `stable`, `3.24.0`, `custom-fork/3.24.0@beta`)
57 
58## Documentation
59 
60Developer docs live in `.context/docs/` and tracked guides under
61`docs/pages/documentation/guides/`. Reference for specific tasks:
62 
63- @README.md - Project overview, release process
64- @CHANGELOG.md - Version history, breaking changes
65- @.github/workflows/README.md - CI/CD pipelines, deployment automation
66- @.context/docs/testing-methodology.md - Test patterns, TestFactory, mocking
67- @.context/docs/integration-tests.md - Real integration guardrails
68- @docs/pages/documentation/guides/manual-smoke-test.md - Isolated final smoke test for git cache, install/use, prompts, symlinks, Melos, VS Code, and cleanup
69- @.context/docs/version-parsing.md - Version parsing regex and logic
70- @.context/docs/v4-release-notes.md - v4.0 architecture changes, migration
71