Flutter Upgrade Manager (fum)

pub package License: BSD-3-Clause

A production-grade, intelligence-driven Flutter project upgrade and migration management tool.

fum is not a simple version bumper. It is a comprehensive compatibility and migration engine that understands the intricate dependency graph connecting Flutter SDKs, Dart SDK constraints, pub packages, Android toolchains (Gradle, AGP, Kotlin, Java, SDKs), and iOS configurations (Deployment Target, CocoaPods, Xcode).

Table of Contents

The Core Philosophy

Traditional approaches blindly bump version numbers, leaving projects broken across build systems. fum treats migrations as an interrelated graph:

Flutter Version
      ↓
Dart SDK Range
      ↓
Package Compatibility (pub.dev API + Semver Analysis)
      ↓
Android Compatibility
  ├── Gradle Wrapper (gradle-wrapper.properties)
  ├── Android Gradle Plugin (AGP)
  ├── Kotlin Gradle Plugin
  ├── Java / JDK Compatibility (Java 11 / 17 / 21)
  └── compileSdk / targetSdk / minSdk / NDK
      ↓
iOS Compatibility
  ├── iOS Deployment Target (Podfile + project.pbxproj)
  ├── CocoaPods Compatibility
  └── Xcode Compatibility

Every planned change is based on verified compatibility rules and evidence, never assumptions.

Installation

Install globally using dart pub:

dart pub global activate flutter_upgrade_manager

Verify the installation:

fum --version
fum --help

Commands Overview

fum doctor

Inspects development machine toolchains, SDKs, and build dependencies:

fum doctor

Checks:

  • Dart SDK
  • Flutter SDK & Channel
  • FVM presence and configuration
  • Git CLI
  • Java JDK version & JAVA_HOME
  • Android SDK (ANDROID_HOME, ANDROID_SDK_ROOT)
  • Gradle CLI & Gradle wrapper
  • Xcode & Command Line Tools (on macOS)
  • CocoaPods & Ruby environment

fum status

Performs an in-depth health and configuration check on the target Flutter project:

fum status

Displays:

  • Project name and path
  • Flutter SDK & Dart SDK constraints
  • FVM status (.fvmrc / .fvm/)
  • Direct and dev dependency counts
  • Android configuration (Gradle, AGP, Kotlin, Java compatibility, SDKs, Groovy vs KTS)
  • iOS configuration (Deployment target, Podfile, schemes)
  • Git repository cleanliness (uncommitted, modified, untracked files)
  • Monorepo structure (Melos, workspaces, sub-packages)

fum plan

The heart of fum. Calculates a full, non-destructive upgrade plan to a target Flutter version without touching any files:

fum plan --flutter 3.40.0
# Or upgrade to latest stable
fum plan --flutter stable

Options:

  • --flutter, -f: Target Flutter version (e.g. 3.24.5, 3.40.0, stable)
  • --project-dir, -p: Path to Flutter project (defaults to current directory)
  • --json: Output machine-readable JSON representation
  • --ci: CI mode (exits with non-zero exit code if conflicts exist)

fum sync

Synchronizes the project dependencies and platform settings with the current or target toolchain:

fum sync
# Safe dry-run
fum sync --dry-run

fum upgrade

Executes the complete end-to-end upgrade workflow:

fum upgrade --flutter 3.40.0

Workflow Steps:

  1. Detects Project: Identifies structure, monorepos, flavors, build files.
  2. Git Safety Check: Ensures working tree is clean (bypassed with --force).
  3. Resolves Compatibility: Calculates Dart, pub.dev packages, Android, and iOS changes.
  4. Interactive Confirmation: Prompts developer with affected files before applying changes (bypass with --yes or -y).
  5. Creates Snapshot Backup: Creates timestamped file backup in .fum/backups/.
  6. Applies Non-Destructive Edits: Updates pubspec.yaml, Gradle, AGP, Kotlin, and Podfile preserving comments and structure.
  7. Resolves Packages: Runs flutter pub get.
  8. Runs Validation: Validates project with analyze and test.

Options:

  • --dry-run: Simulate upgrade without modifying files
  • --force: Bypass Git safety checks for dirty working tree
  • -y, --yes: Auto-confirm file modifications
  • --json: Machine-readable output
  • --no-validate: Skip post-upgrade validation steps

fum diff

Displays precise OLD → NEW differences for the planned upgrade:

fum diff --flutter 3.40.0

Outputs changed fields across Flutter, Dart, dependencies, Android, and iOS, along with affected file paths.

fum validate

Executes health and build validation suites:

fum validate
# For CI/CD pipelines
fum validate --ci

Runs:

  • flutter pub get
  • flutter analyze
  • flutter test
  • Android Gradle verification (./gradlew tasks --dry-run)

fum backup

Manually creates a timestamped snapshot of project configuration files:

fum backup

Backups are saved to:

.fum/backups/<timestamp>/
.fum/migrations/<timestamp>.json

fum rollback

Restores project files safely to a previous state:

# Rollback to the most recent backup
fum rollback --latest

# Rollback to a specific migration ID
fum rollback --id 2026-09-28_10-30-00

fum why

Explains the full chain of compatibility constraints requiring a specific component:

fum why dart
fum why gradle
fum why java
fum why agp

Traces the dependency graph backwards to show exactly why a version is required — which upstream component drives the constraint.

fum conflicts

Detects and displays all compatibility conflicts across toolchains and packages:

fum conflicts
fum conflicts --json
fum conflicts --ci    # Non-zero exit on conflicts

fum explain

Explains the rationale and compatibility requirements behind all planned file modifications:

fum explain --flutter 3.40.0

Shows for each affected file (pubspec.yaml, gradle-wrapper.properties, build.gradle, Podfile, project.pbxproj) exactly what will change and why.

fum dependencies

Comprehensive dependency analysis:

fum dependencies              # Summary of direct, dev, and transitive deps
fum dependencies graph        # Full dependency graph
fum dependencies outdated     # List outdated packages
fum dependencies conflicts    # Identify version conflicts
fum dependency-tree <package> # ASCII tree for a specific package

fum repair

Automatically detects and fixes common build and configuration mismatches:

fum repair              # Apply fixes
fum repair --dry-run    # Preview fixes without modifying files
fum repair --yes        # Auto-confirm

Fixes include:

  • Kotlin JVM target / Java targetCompatibility alignment
  • Insecure Gradle wrapper http:// → https:// URLs
  • Outdated iOS Podfile deployment targets

fum health

Performs a multidimensional category-level project readiness audit:

fum health

Evaluates readiness across: Flutter SDK, Dart SDK, Android toolchain, iOS toolchain, dependencies, security, and configuration.

fum history

Lists and inspects past migration transactions:

fum history                  # List all migrations
fum history show <id>        # Inspect specific migration
fum history --json           # Machine-readable output

fum policy

Verifies project compliance against enterprise governance policies:

fum policy check
fum policy check --ci    # Non-zero exit on policy violations

Checks dependency update policies, prohibited licenses, security constraints, and custom enterprise rules configured in .fum.yaml.

fum security

Audits dependencies for security advisories, discontinued packages, and risks:

fum security

Reports discontinued packages, known vulnerabilities, and suggests replacements.

fum licenses

Analyzes licenses of all project dependencies and verifies compliance:

fum licenses

Checks against prohibited license lists configured in .fum.yaml enterprise policies.

fum cache

Manages local metadata, pub, and compatibility rule caches:

fum cache              # Show cache status
fum cache status       # Detailed cache info
fum cache clear        # Clear all caches
fum cache update       # Refresh remote caches

Compatibility Engine & Matrix

fum includes an extensible multi-source compatibility architecture:

CompatibilityRepository
      ↓
LocalCompatibilitySource (Verified embedded database)
      ↓
RemoteCompatibilitySource (Official remote updates)
      ↓
CompatibilityCache (.fum/cache/)
      ↓
CompatibilityEngine
  • No Faked Data: If a version combination is outside verified boundaries, it is reported as unknown requiring manual verification.
  • Offline Resilience: Fully operational offline using local embedded rules and cached queries.

Safety & Rollback Architecture

Modifying project files demands rigorous safety guarantees:

  1. Pre-flight Git Verification: Detects uncommitted and untracked changes.
  2. Manifest Tracking: Records SHA-256 hashes of all files before migration.
  3. Structured Parsing: Uses yaml_edit and balanced token parsers for Groovy and Kotlin DSL, preserving user comments, code, and custom blocks.
  4. Explicit Rollback: Instant restoration with zero file residue.

Configuration (.fum.yaml)

Customize upgrade policies by placing .fum.yaml in your project root:

flutter:
  version: "3.40.0"

upgrade:
  auto_confirm: false
  create_backup: true

android:
  update_compile_sdk: true
  update_target_sdk: true
  update_min_sdk: false

ios:
  update_deployment_target: true

packages:
  allow_major_updates: false
  allow_minor_updates: true
  allow_patch_updates: true

safety:
  require_clean_git: true

CI / CD Integration

Use --json and --ci flags in GitHub Actions, GitLab CI, or Bitbucket Pipelines:

- name: Validate Flutter Project Health
  run: fum validate --ci

- name: Check Upgrade Plan for Incompatibilities
  run: fum plan --flutter stable --ci --json

Exit Codes

Code Meaning
0 Success
1 General Failure
2 Invalid Arguments
3 Compatibility Conflict
4 Validation Failure
5 Git Safety Failure
6 Rollback Failure

Monorepos and Flavors

  • Monorepos: Automatically detects Melos (melos.yaml), Pub workspaces (workspace:), and nested packages.
  • Flavors & Schemes: Detects and preserves Android productFlavors and iOS .xcscheme scheme configurations.

Architecture

Built using layered Domain-Driven Architecture:

lib/
├── flutter_upgrade_manager.dart
└── src/
    ├── domain/           # Models, rules, value objects, exceptions, exit codes
    ├── application/      # Use cases, project detector, CLI commands
    ├── infrastructure/   # Filesystem, process runner, Git, pub.dev, Android, iOS
    ├── compatibility/    # Multi-dimensional compatibility resolvers
    ├── planning/         # Plan generation, conflict resolution, migration
    ├── validation/       # Health checks and CI validators
    ├── backup/           # Backup and rollback engine
    └── reporting/        # Console, diff, and JSON formatters

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on code style, tests, and pull request guidelines.

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

Libraries

flutter_upgrade_manager
Flutter Upgrade Manager (fum)