wex_addon_dev_flutter

Version: 6.9.9

A wex addon for developers who maintain Flutter and Dart packages: it registers three workdir types — flutter, flutter-package, and flutter-packages-suite — that enforce the expected directory layout (pubspec.yaml, lib/, test/, .publignore), auto-format every .dart file via dart format, and drive flutter pub publish for releases. The flutter-package workdir also keeps pubspec.yaml consistent, writing the package name, version, and GitHub URLs resolved from the repository remote.

Table of Contents

• Installation
• Quickstart
• Tests
• Architecture
• Integration in the Suite
• Dependencies
• Versioning & Compatibility Policy
• License
• About us
• Known Limitations & Roadmap
• Status & Compatibility
• Useful Links
• Migration Notes

Installation

pip install wexample-wex-addon-dev-flutter

Requires Python >=3.10.

Quickstart

Install the package:

pip install wexample-wex-addon-dev-flutter

The public entry point is FlutterAddonManager, defined in src/wexample_wex_addon_dev_flutter/flutter_addon_manager.py:

from wexample_wex_addon_dev_flutter.flutter_addon_manager import FlutterAddonManager

Pass it to the kernel's setup() call to register the Flutter workdir types:

from wexample_wex_core.common.kernel import Kernel

kernel = Kernel()
kernel.setup(addons=[FlutterAddonManager])

After setup() returns, the kernel recognises three workdir types — flutter, flutter-package, and flutter-packages-suite — mapped by get_workdir_types(). A flutter workdir enforces the presence of pubspec.yaml, lib/, test/, and .publignore, and applies dart format to every .dart file it finds under lib/ and test/. A flutter-package workdir extends that with auto-generated pubspec.yaml metadata (name, version, homepage, repository, and issue tracker resolved from the Git remote) and README generation. A flutter-packages-suite workdir treats each subdirectory that contains a pubspec.yaml as a flutter-package child.

The manager carries no CLI commands; registering it is the registration.

Tests

This project uses pytest for testing and pytest-cov for code coverage analysis.

Installation

First, install the required testing dependencies:

.venv/bin/python -m pip install pytest pytest-cov

Basic Usage

Run all tests with coverage:

.venv/bin/python -m pytest --cov --cov-report=html

Common Commands

# Run tests with coverage for a specific module
.venv/bin/python -m pytest --cov=your_module

# Show which lines are not covered
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing

# Generate an HTML coverage report
.venv/bin/python -m pytest --cov=your_module --cov-report=html

# Combine terminal and HTML reports
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html

# Run specific test file with coverage
.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing

Viewing HTML Reports

After generating an HTML report, open htmlcov/index.html in your browser to view detailed line-by-line coverage information.

Coverage Threshold

To enforce a minimum coverage percentage:

.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80

This will cause the test suite to fail if coverage drops below 80%.

Architecture

The addon is a thin Python package whose only job is to extend the wex kernel with Flutter-aware workdir types. No CLI commands are added; registration is the feature.

Entry point

src/wexample_wex_addon_dev_flutter/flutter_addon_manager.py defines FlutterAddonManager, which extends AbstractAddonManager from wexample_wex_core. Its sole method, get_workdir_types(), returns the mapping the kernel uses to resolve workdir type strings at runtime:

{
    "flutter": FlutterWorkdir,
    "flutter-package": FlutterPackageWorkdir,
    "flutter-packages-suite": FlutterPackagesSuiteWorkdir,
}

All three workdir classes are imported lazily inside get_workdir_types() to avoid circular imports at module load time.

Workdir hierarchy

FlutterWorkdir

src/wexample_wex_addon_dev_flutter/workdir/flutter_workdir.py is the base class for both Flutter workdir types. It inherits CodeBaseWorkdir (from wexample-wex-addon-app), WithAiWorkdirMixin, and WithLicenseWorkdirMixin.

prepare_value() is where the expected on-disk structure is declared. It appends to the filestate children list:

• pubspec.yaml — mapped to FlutterPubspecYamlFile, required to exist.
• lib/ and test/ — required directories; each carries a ChildrenFilterOption that matches every *.dart file (recursively) and attaches DartFormatOption to it, so dart format runs on every Dart source the filestate visits.
• .publignore — required to exist.
• A .gitignore section named Flutter covering .dart_tool/, build/, .packages, and the platform-specific plugin manifests.

get_options_providers() appends FlutterOptionsProvider from wexample-filestate-flutter to the list returned by the parent, which is how Dart-specific filestate options become available to the tree.

get_app_config_file() returns the FlutterPubspecYamlFile child, reading it once so its content is populated.

_publish() shells out to flutter pub publish --dry-run first, then flutter pub publish, routing through _safe_shell() which swallows exit code 65 (pub's warning-only exit) and re-raises everything else.

FlutterPackageWorkdir

src/wexample_wex_addon_dev_flutter/workdir/flutter_package_workdir.py extends FlutterWorkdir with package-specific behaviour:

• _get_critical_directories() declares lib/ as the one directory whose absence is a hard error.
• _get_readme_content() returns a FlutterPackageReadmeContentConfigValue instance, wiring in Flutter-specific README generation.
• _get_suite_workdir_class() returns FlutterPackagesSuiteWorkdir, so the suite layer knows which class to use when walking a multi-package repository.

FlutterPackagesSuiteWorkdir

src/wexample_wex_addon_dev_flutter/workdir/flutter_packages_suite_workdir.py extends FrameworkPackageSuiteWorkdir from wexample-wex-addon-app. It identifies child package directories by checking for the presence of pubspec.yaml (_child_is_package_directory()), names the child workdir type "flutter" (_get_children_package_directory_name()), and hands back FlutterPackageWorkdir as the class to instantiate for each child (_get_children_package_workdir_class()).

File model

src/wexample_wex_addon_dev_flutter/file/flutter_pubspec_yaml_file.py extends YamlFile. Its dumps() method is called whenever the filestate writes the file to disk. It:

1. Sets name from workdir.get_package_name() and version from workdir.get_setup_version().
2. Resolves the deployment remote URL via git remote get-url.
3. If the remote is a GitHub URL, fills in homepage, repository, and issue_tracker (only where those keys are absent in the current content).

get_dependencies_versions() reads dependencies and, when group="dev", merges dev_dependencies on top, returning a flat dict[str, str].

README generation

src/wexample_wex_addon_dev_flutter/config_value/flutter_package_readme_config_value.py extends AppReadmeConfigValue. The only override is _get_app_description(), which reads the description field from pubspec.yaml (via workdir.get_app_config()) and falls back to the parent implementation when that field is absent.

Call path for a filestate apply

1. The kernel resolves "flutter-package" → FlutterPackageWorkdir via FlutterAddonManager.get_workdir_types().
2. FlutterPackageWorkdir.prepare_value() (inherited from FlutterWorkdir) builds the expected tree, declaring pubspec.yaml, lib/, test/, .publignore, and the gitignore block.
3. For each *.dart file under lib/ or test/, the ChildrenFilterOption attaches DartFormatOption; the filestate runner calls dart format on it.
4. When the filestate visits pubspec.yaml, it delegates to FlutterPubspecYamlFile.dumps(), which writes name, version, and GitHub URLs.
5. _get_readme_content() returns a FlutterPackageReadmeContentConfigValue whose _get_app_description() pulls the description from the freshly resolved pubspec.yaml.

Integration in the Suite

This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.

Related Packages

The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.

Visit the Wexample Suite documentation for the complete package ecosystem.

Dependencies

• attrs: >=23.1.0
• cattrs: >=23.1.0
• wexample-filestate-flutter: >=6.6.0
• wexample-wex-addon-ai: >=16.1.0
• wexample-wex-addon-app: >=32.2.0

Versioning & Compatibility Policy

Wexample packages follow Semantic Versioning (SemVer):

• MAJOR: Breaking changes
• MINOR: New features, backward compatible
• PATCH: Bug fixes, backward compatible

We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Free to use in both personal and commercial projects.

About us

Wexample stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.

This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.

Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.

Known Limitations & Roadmap

Current limitations and planned features are tracked in the GitHub issues.

See the project roadmap for upcoming features and improvements.

Status & Compatibility

Maturity: Production-ready

Python Support: >=3.10

OS Support: Linux, macOS, Windows

Status: Actively maintained

Useful Links

• Homepage: https://github.com/wexample/python-wex-addon-dev-flutter
• Documentation: docs.wexample.com
• Issue Tracker: https://github.com/wexample/python-wex-addon-dev-flutter/issues
• Discussions: https://github.com/wexample/python-wex-addon-dev-flutter/discussions
• PyPI: pypi.org/project/wexample-wex-addon-dev-flutter

Migration Notes

When upgrading between major versions, refer to the migration guides in the documentation.

Breaking changes are clearly documented with upgrade paths and examples.