leoafarias/fvm

This system is FVM, a command-line tool for managing multiple Flutter SDK versions within development projects. It provides capabilities to install, switch, and cache specific SDK channels (stable, beta, dev) while handling project-level configuration and dependency resolution. The system exposes its functionality through a structured CLI and a programmatic JSON API, enabling integration with external tooling and IDEs.

13 changes.

The project migrated its core library implementation from Go to Dart, restructuring the codebase into a modular, composable architecture with distinct workflow classes. This period also introduced significant tooling enhancements, including a new API command for machine-readable output, native executable compilation scripts, and comprehensive test coverage for the new Dart-based components.

14 changes.

This period focused on refactoring the codebase into a structured service layer, introducing new services for configuration, caching, and project management. It also added a new JSON API for programmatic access and comprehensive test coverage for the updated services and command-line operations.

6 changes.

The project introduced a standalone fvm\_mcp server to expose FVM capabilities via the Model Context Protocol, enabling AI-driven tooling interactions. Concurrently, test coverage was significantly expanded across service layers, workflows, and integration scenarios, while release tooling was modularized into a dedicated package to improve maintainability and automation.

The project now automatically runs static analysis and formatting checks before commits and pushes. The pre-commit hook executes \lint\_staged\ on changed files and runs \dart analyze --fatal-infos\ across the entire project, while also optionally running DCM analysis if the tool is installed. The pre-push hook ensures the codebase is clean by running \dart analyze\ and DCM again, and explicitly configures the PATH to include Flutter/Dart binaries to prevent issues when running these checks from GUI applications.

.husky · high confidence

A new standalone \fvm\_mcp\ package is released as an alpha server that exposes FVM capabilities as MCP tools. It provides read-only JSON API tools (\fvm.api.list\, \fvm.api.releases\, \fvm.api.context\, \fvm.api.project\) and mutating tools (\fvm.install\, \fvm.remove\, \fvm.use\, \fvm.global\) that are gated by the installed FVM version (JSON API requires FVM ≥ 3.1.2; mutating tools require FVM ≥ 3.2.0 for non-interactive support). The server also includes proxy tools (\fvm.flutter\, \fvm.dart\, \fvm.exec\, \fvm.spawn\) and is designed to be run via stdio from source or as a prebuilt binary on Linux, macOS, and Windows. This location provides the server implementation, argument utilities, process runner, and version detection logic, while the README documents how to embed the server into the FVM CLI via a new \fvm mcp\ subcommand.

_fvm\mcp · high confidence

Added a new set of typed response models in \lib/src/api/models/json\_response.dart\ to standardize how the application handles JSON data for cache versions, cleanup operations, releases, projects, and context. These models, powered by the \dart\_mappable\ library, provide structured serialization and deserialization for API interactions, replacing ad-hoc map handling with strongly-typed classes like \GetCacheVersionsResponse\, \GetCleanupResponse\, and \GetReleasesResponse\.

lib/src/api/models · high confidence

This change adds a comprehensive set of utility files to the project's core library. It introduces a \ChangeCase\ class for converting strings to camelCase, snake\_case, and other formats, alongside a \compareSemver\ function for semantic version comparison. A new \FvmContext\ class centralizes application state, configuration, and dependency injection, including logic for detecting CI environments and managing git cache settings. Additionally, the update includes helpers for parsing Flutter and Dart version outputs, utilities for handling file locks and directory operations with Windows-specific retry logic, and tools for tracking git clone progress and resolving executable paths.

lib/src/utils · high confidence

A new \fvm api\ command has been added to provide structured JSON access to FVM data, enabling better integration with external tooling and IDEs. This command includes subcommands for listing installed SDK versions (\api list\), viewing available releases (\api releases\), checking environment context (\api context\), retrieving project configuration (\api project\), and identifying cleanup candidates (\api cleanup\). All outputs support a \--compress\ flag for compact JSON formatting, and the list command offers a \--skip-size-calculation\ flag to improve performance on large caches.

lib/src/commands · high confidence

A new FlutterReleaseClient service has been introduced to manage Flutter SDK release data. This client implements an instance-level cache to avoid redundant network requests and includes a robust fallback mechanism: it attempts to fetch release metadata from a GitHub-hosted JSON file first, and if that fails, it falls back to Google Cloud Storage. The service also provides methods to retrieve releases by channel, validate specific versions, and fetch the latest release for a given channel.

_lib/src/services/releases\service · high confidence

A new \ApiService\ has been introduced in \lib/src/api\ to expose FVM data via a structured JSON interface, enabling integrations and external tooling to query the current context, project details, cached SDK versions (including size and unreferenced status), cleanup plans (upgrades and unused SDKs), and available Flutter releases with filtering options.

lib/src/api · high confidence

A new script, bin/compile.dart, has been added to the project. This script automates the process of compiling the FVM Dart package into a native executable and installing it to /usr/local/bin on macOS and Linux systems. It handles the compilation via \dart compile exe\, moves the resulting binary to the system destination, and deactivates any previously globally activated version of FVM. The existing bin/main.dart entry point remains unchanged, continuing to serve as the standard CLI runner.

bin · high confidence

The \lib/src/models\ directory now includes several new mappable data classes to support version tracking and configuration management. \CacheFlutterVersion\ represents a cached Flutter SDK with metadata (version strings, setup status) loaded from disk, handling both modern JSON metadata and legacy version files. \CleanupAction\ and \PatchUpgrade\ models define the structure for applying cached patch upgrades and managing unused SDK cleanup. \ConfigOptions\ and related config classes (\EnvConfig\, \AppConfig\, \LocalAppConfig\) provide a structured way to handle global and local FVM settings, including cache paths and git cache options. Additionally, \FlutterRootVersionFile\ parses the \flutter.version.json\ metadata, and \GitReference\ models support parsing git branches and tags for version resolution.

lib/src/models · high confidence

The tool directory now includes a Homebrew formula template (fvm.template.rb) for packaging FVM as a macOS formula, a grinder script (grind.dart) to automate compilation, testing, and coverage tasks, and a utility (record\_test\_fixtures.dart) to generate test fixtures for Flutter version metadata and release data.

tool · high confidence

The \beta\, \dev\, \master\, \prune\, \remove\, \stable\, and \root\ commands have been removed from the CLI. These files contained only stub implementations (e.g., printing a name or empty run functions) and are no longer part of the application.

cmd · high confidence

The \lib/src/workflows\ directory has been restructured from a monolithic implementation into a set of distinct, single-responsibility workflow classes. This change introduces new components such as \CheckProjectConstraintsWorkflow\ for validating SDK versions against project constraints, \EnsureCacheWorkflow\ for managing local SDK caching and integrity, and \ResolveProjectDependenciesWorkflow\ for handling \pub get\ operations. It also adds dedicated workflows for IDE and tooling integration, including \UpdateVsCodeSettingsWorkflow\ and \UpdateMelosSettingsWorkflow\, as well as \SetupGitIgnoreWorkflow\ for repository hygiene. The \UseVersionWorkflow\ now orchestrates these components, providing a cleaner separation of concerns for version switching, setup, and dependency resolution.

lib/src/workflows · high confidence

This release updates the FVM CLI to version 4.3.1. The core command runner has been restructured to use the \CompletionCommandRunner\ from the \cli\_completion\ package, enabling shell completion support. It now includes explicit registration for commands such as \flavor\, \integration\_test\, and \exec\. The runner also implements automatic update checks via \pub\_updater\, displaying a prompt if a newer version is available, and warns users about deprecated or legacy environment variables like \FVM\_GIT\_CACHE\ and \FVM\_HOME\.

lib/src · high confidence

The core library implementation has been migrated from Go to Dart. The previous Go-based setup logic (lib/setup.go), which handled cloning Flutter channels, renaming version directories, and running doctor checks, has been removed. It is replaced by a new Dart entry point (lib/fvm.dart) that exports a comprehensive set of models (cache, config, versions), services (cache, project, releases), and utilities (git, context, exceptions) to support the Flutter Version Management tool's functionality.

lib · high confidence

The \lib/src/services\ directory has been refactored into a structured service layer. \AppConfigService\ now handles configuration merging from global, environment, and project sources, including legacy \FVM\_HOME\ support. \CacheService\ manages the local SDK cache, including version matching and fork directory cleanup. \CleanupService\ introduces a new plan-based approach to identify unused SDKs and patch upgrades. \ProjectRegistryService\ tracks known project roots to improve the accuracy of the \fvm list\ unused SDK detection. \GitService\ and \FlutterService\ manage the git cache and SDK cloning, with improved error handling for cache corruption. \ProcessService\ now scrubs git-specific environment variables to prevent repository context leakage. \LoggerService\ provides a unified interface for logging and interactive prompts.

lib/src/services · high confidence

The release automation scripts have been reorganized into a standalone \tool/release\_tool\ package, separating them from the main project root. This change introduces a new \grind.dart\ entry point that configures \cli\_pkg\ for publishing the FVM tool to GitHub and Homebrew, including a specific fix to use the canonical repository owner to prevent deployment failures during account redirects. The new structure includes dedicated analysis options and unit tests for the release logic, such as fetching GitHub releases and handling HTTP requests, ensuring the tooling is more modular and testable.

_tool/release\tool · high confidence

The releases service models have been refactored to use the \dart\_mappable\ library for serialization and deserialization. New \FlutterReleasesResponse\ and \FlutterSdkRelease\ classes now handle parsing the release API payload, including mapping JSON fields like \release\_date\ and \dart\_sdk\_arch\ to their respective Dart properties. This change introduces generated mapper files to handle object instantiation and copying, replacing previous manual parsing logic and ensuring consistent, type-safe handling of release channel data (stable, beta, dev) and SDK metadata.

_lib/src/services/releases\service/models · high confidence

The tool's local release manifests (releases\_macos.json, releases\_windows.json, releases\_linux.json) have been updated with the latest available Flutter SDK versions from the official Google Storage channel, ensuring the CLI can discover and install the most recent stable, beta, and dev builds. This change is accompanied by a version bump to the tool itself, reflecting the latest release cycle.

(repo-wide) · high confidence

Added comprehensive test suite for FVM commands and version handling; Added integration test for FVM v3 to current cache migration; Added service-layer test coverage for configuration, caching, and Git operations; Added test helpers for fast, deterministic Flutter SDK and service mocking; Added test support assets for PTY-based SIGINT cleanup verification; Added tests for API, cleanup, destroy, list, and remove commands; Added tests for FVM service layer logic; Added tests for path conversion, file lock detection, and git clone progress tracking; Added unit tests for FlutterVersion model; Added unit tests for cache, root version, and project registry models; Added unit tests for utility functions; Expanded test coverage for FVM command-line operations; Expanded test coverage for FVM workflow behaviors; New local testing and migration validation scripts for FVM.

The project now includes a new Nextra-based documentation site under the docs folder, introducing dependencies such as Next.js, React, Tailwind CSS, and Algolia DocSearch. Additionally, a new FVM MCP server package (fvm\_mcp) has been added, bringing in the dart\_mcp library to expose FVM as tools, alongside standard Dart utilities like process and pub\_semver. The main FVM CLI and its release tooling have also updated their dependency sets, with the release tool specifically adopting cli\_pkg 2.14.0 for automation.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 67.

• Code Health 92
• Architecture 98
• Maturity 61
• Readiness 62
• Security 65
• Domain Modelling 100

• 300 commits — 239 feature/other, 61 fixes

• (root) — 173 commits
• lib/src — 53 commits
• docs/pages — 22 commits
• .github/workflows — 19 commits
• (repo) — 13 commits
• docs/public — 5 commits
• .context/docs — 3 commits
• .github/actions — 2 commits
• .github/ISSUE_TEMPLATE — 1 commit
• .github/copilot-instructions.md — 1 commit
• fvm_mcp/lib — 1 commit
• test/commands — 1 commit
• test/commands_test.dart — 1 commit
• test/services — 1 commit
• test/src — 1 commit
• tool/grind.dart — 1 commit
• v4.0-release-audit/FVM_v4.0_CHANGELOG_DRAFT.md — 1 commit
• v4.0-release-audit/FVM_v4.0_DETAILED_AUDIT.md — 1 commit

• fix: Fix broken links #915 on documentation (#937)
• fix: Fix git cache rebuild stale installs
• fix: Fix installation step in quickstart (#865)
• fix: Fix macOS installer arch detection under Rosetta (#1025)
• fix: Fix route conflict (#980)
• fix: Fix: Support legacy .fvm/fvm_config.json file loading (#996)
• fix: Merge pull request #1037 from leoafarias/fix/git-cache-bloat
• fix: Merge remote-tracking branch 'origin/main' into fix/git-cache-bloat
• fix: Merge remote-tracking branch 'origin/main' into fix/git-cache-bloat
• fix: Merge remote-tracking branch 'origin/main' into fix/git-cache-bloat
• fix: Merge remote-tracking branch 'origin/main' into fix/git-cache-bloat
• fix: chore: apply code formatting and linter fixes (#861)
• fix: chore: apply dart format, dart fix, and dcm fix (#1040)
• fix: chore: apply dart format, dart fix, and dcm fix across codebase (#1039)
• fix: chore: regenerate build runner and apply formatting fixes (#957)
• fix: fix(docs): correct broken links in getting started page (#945)
• fix: fix: Enhance install.sh with Alpine/musl support and better error handling (#949)
• fix: fix: Handle fork install fallback correctly (#887)
• fix: fix: add --force flag to pub dry-run validation (#924)
• fix: fix: add git commit step to create clean state for pub.dev validation (#911)
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

leoafarias/fvm was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.