flutter_setup 0.1.0

A reusable Flutter project scaffolding CLI tool.

flutter_setup

A reusable Flutter project scaffolding CLI tool.

Overview

flutter_setup is a Dart CLI package designed to automate the scaffolding of Flutter applications using customizable architecture templates, predefined folder structures, dependency packages, configuration, and boilerplate.

• Phase 1: Built the CLI engine foundation, argument parsing, command architecture, template discovery/loading, template configuration validation, and terminal output formatting.
• Phase 2: Built a standalone, framework-agnostic Template Engine (variable case conversions, token substitution in file names and contents, YAML folder creation, destination safety).
• Phase 3: Built real Flutter Project Generation by orchestrating flutter create process execution with template rendering.
• Phase 4: Built the Package Manager (dependencies and dev_dependencies installation via flutter pub add and flutter pub get).
• Phase 5: Built the Assets Generator (binary file preservation, automated asset scanner, pubspec.yaml assets: registration, and type-safe Assets constant class generation).
• Phase 6: Populated real Production Boilerplate into the default template (Dio network client, GoRouter navigation, Material 3 light/dark theme, Riverpod state management, failure handling, and an end-to-end example feature).
• Phase 7: Built Multiple Template Support (default and minimal) driven entirely by directory discovery (templates/<name>/) with zero engine hardcoding.
• Phase 8: Built Interactive Mode (flutter_setup create with no args) using a decoupled Prompter abstraction and a unified CreateProjectRequest pipeline.
• Phase 9: Built Safety Hardening & Full-Pipeline Test Audit (automatic project rollback on partial failure, --force (-f) flag for non-interactive overwrite, interactive destination conflict prompts (Cancel, Overwrite, Choose a different name), SDK & process failure guards, and full-pipeline integration tests).
• Phase 10: Built the Feature & Sub-Component Generator (feature, screen, model, repository generation into existing Flutter projects with project validation, conflict detection, scoped rollback, and route wiring reminders).

Interactive Mode & CLI Usage

Running flutter_setup create with no arguments triggers Interactive Mode:

$ flutter_setup create
? Project name: ecommerce_app
? Description (A new Flutter project.): My E-Commerce App
? Template
  1) default (default)
  2) minimal
Select an option (1-2) [default]: 1

Non-interactive usage (flutter_setup create my_app --template minimal [--force]) remains 100% supported and scriptable.

Working Commands:

• flutter_setup / flutter_setup --help / flutter_setup -h
• flutter_setup --version / flutter_setup version / flutter_setup -v
• flutter_setup templates
• flutter_setup info <template_name>
• flutter_setup create (Interactive mode)
• flutter_setup create <project_name> [--template <template_name>] [--force] (Non-interactive project creation)
• flutter_setup feature <feature_name> [--path <path>] (Generate feature skeleton)
• flutter_setup screen <name> --feature <feature_name> [--path <path>] (Generate screen)
• flutter_setup model <name> --feature <feature_name> [--path <path>] (Generate domain model)
• flutter_setup repository <name> --feature <feature_name> [--path <path>] (Generate repository)

---

Safety & Destination Conflict Resolution

1. Existing Destination Handling

• Non-Interactive Mode: Refuses to overwrite existing project directories unless the --force (-f) flag is explicitly supplied.
• Interactive Mode: Automatically detects existing directories and prompts for user action via Prompter:
  1. Cancel: Aborts generation cleanly without altering disk.
  2. Overwrite: Deletes existing directory contents before running flutter create.
  3. Choose a different name: Re-prompts for a new project name and validates destination.

2. Automatic Partial-Failure Rollback

If an error occurs at any point after flutter create spawns (e.g. template rendering failure, invalid package name, network disconnection during pub add/pub get, asset generation error), flutter_setup automatically deletes the partially-created project directory from disk. No corrupted or incomplete project files are left behind.

---

How Project Generation & Asset Registration Work

When you execute:

flutter_setup create my_app

The CLI executes the following orchestration steps:

1. Validation: Validates my_app as a valid Flutter/Dart package identifier.
2. Destination Check: Verifies ./my_app does not already exist on disk (unless --force is used or Overwrite is selected interactively).
3. Flutter Baseline Scaffolding: Executes flutter create my_app to generate standard Flutter platform folders (android/, ios/, web/), .gitignore, and pubspec.yaml.
4. Template Overlay: Invokes TemplateRenderer to layer template files (lib/main.dart, app_constants.dart, assets, etc.) and YAML-declared folders over the generated project. Binary files (.png, .jpg, .ttf, etc.) are preserved byte-for-byte.
5. Package Installation: Installs dependencies and dev_dependencies declared in template.yaml via flutter pub add and resolves packages with flutter pub get.
6. Asset Processing:
   • Scanner: Discovers all files inside the project's assets/ folder.
   • Pubspec Registration: Safely inserts/merges discovered asset paths into pubspec.yaml under flutter: assets:.
   • Assets Class Generation: Generates a type-safe Assets class (at lib/core/constants/assets.dart or custom path declared in generated_files.assets_class).
7. Summary Report: Prints success metrics, installed packages, asset registration status, and next steps.

---

Asset Conventions & Usage

1. Template Structure

Place assets inside the template's files/assets/ directory:

templates/default/files/assets/
├── images/
│   └── logo.png
└── icons/
    └── app_icon.png

2. Type-Safe Assets Class

The generator automatically builds lib/core/constants/assets.dart:

// GENERATED FILE - DO NOT EDIT BY HAND
class Assets {
  Assets._();

  static const String iconsAppIcon = 'assets/icons/app_icon.png';
  static const String imagesLogo = 'assets/images/logo.png';
}

Usage in Flutter widgets:

Image.asset(Assets.imagesLogo)

---

Feature & Sub-Component Generation

Generate code into an existing Flutter project cleanly and safely.

1. Generate a Full Feature Skeleton

cd my_app
flutter_setup feature payments

Generates:

lib/features/payments/
├── data/
│   ├── datasources/
│   │   └── payments_remote_datasource.dart
│   └── repositories/
│       └── payments_repository.dart
├── domain/
│   └── payments_model.dart
└── presentation/
    ├── providers/
    │   └── payments_provider.dart
    └── screens/
        └── payments_screen.dart

Prints manual route reminder: Don't forget to add a route for PaymentsScreen in lib/core/router/app_router.dart

2. Generate Single Sub-Components

Add individual screens, domain models, or repositories to an existing feature:

flutter_setup screen checkout --feature payments
flutter_setup model payment_intent --feature payments
flutter_setup repository payment --feature payments

3. Safety & Scoped Rollback

• Project Validation: Confirms execution inside a valid Flutter project (checks for pubspec.yaml with flutter: key).
• Conflict Prevention: Refuses to overwrite pre-existing user files.
• Scoped Rollback: If multi-file generation fails halfway, ONLY files created during that specific invocation are cleaned up. Pre-existing project files remain untouched.

---

Getting Started

Prerequisites

• Dart SDK 3.0.0 or higher
• Flutter SDK on system PATH

Installation & Execution

Run locally with dart:

dart pub get
dart run bin/flutter_setup.dart create my_app

Or activate globally:

dart pub global activate --source path "."
flutter_setup create my_app

Running Tests

# Full test suite with randomized ordering
dart test --test-randomize-ordering-seed=random