cleany 2.0.0
cleany: ^2.0.0 copied to clipboard
Interactive Flutter architecture CLI for features and components with Cubit or Bloc, Freezed, safe generation, project repair, and native flavors.
CLEANY #
Release 2.0.0 · Interactive architecture tooling for Flutter.
Cleany creates features and reusable components using one consistent Feature-Based + Clean Architecture template, with Cubit or Bloc, Freezed, and multiple_result. A numbered terminal menu guides each operation, validates the generated project in isolation, and applies changes with recoverable file updates.
Installation · Quick start · Architecture · Menu guide · Safety · Usage guide
What you get #
- Full features with Data, Domain, and Presentation layers.
- Lightweight components with optional Cubit/Bloc, without unnecessary data layers.
- Cubit/Bloc selection for every feature; immutable Freezed states.
- Central GetIt composition, controller factories, and go_router integration through Dart AST edits.
- Direct Dio or Retrofit over Dio, with a dedicated client and auth interceptor.
- Raw JSON datasources; repository-owned Model → Entity and exception → Failure conversion.
Result<Entity, Failure>from multiple_result; Domain stays independent of Dio, Retrofit, and GetIt.- Compact response fields:
fieldName:type:jsonKey, followed by y/n nullability. - Official Flutter Arabic/English localization, ARB files, gen-l10n, and RTL support.
- Dev/UAT/prod bootstrap and guided native Flavorizr setup.
- Custom locations inside
lib, nested features, ownership tracking, safe removal, and rename/move. - Project Doctor, interrupted-operation recovery, local cache cleanup, and archived reset.
- Progress, command deadlines, cancellation, and retryable input/operation errors.
The template is fixed. Cleany does not require a database SDK or a custom template system.
Requirements and platform support #
| Requirement | Details |
|---|---|
| Dart for Cleany | 3.13.0 or newer within Dart 3.x |
| Flutter | A stable Flutter SDK available on PATH for package resolution, builders, localization, and analysis |
| CLI host systems | Linux, macOS, Windows |
| Native flavor setup | Android, iOS, macOS folders already present in the project; platform-specific toolchains must be installed |
| Verified local environment | Flutter 3.47.7 / Dart 3.13.5 on macOS |
Cleany runs on the developer's computer. Its pub.dev platform declarations describe the CLI host, while the generated application uses Flutter. Cleany is not a mobile or browser runtime dependency. CI covers Linux/macOS/Windows; an available CI configuration does not by itself prove a successful run on every system. Native project configuration tests do not replace signed builds or device testing.
Installation #
After this release is published to pub.dev:
dart pub global activate cleany 2.0.0
For the current checkout, activate the local source instead:
# Run from the Cleany repository.
dart pub global activate --source path .
Add the pub-cache bin directory to PATH if cleany is not found. Typical locations are $HOME/.pub-cache/bin on macOS/Linux and %LOCALAPPDATA%\Pub\Cache\bin on Windows. You can also invoke the installed executable with:
dart pub global run cleany:cleany
After updating a local installation, close any running Cleany session and start it again.
Quick start #
- Create or open a Flutter project and enter its root directory.
- Run
cleany. - Choose 7 — Initialize project, select the production identity and API provider, then apply.
- Choose 1 — Create feature, enter a name, select Cubit/Bloc, and choose a location.
- Select default response fields or define your own fields, then apply and validate.
- Configure the API base URL and run the chosen application entrypoint.
flutter create playground
cd playground
cleany
Cleany presents:
╭────────────────────────────────────────────╮
CLEANY · Flutter Architecture
╰────────────────────────────────────────────╯
1 Create feature
2 Create component
3 List features
4 List components
5 Remove feature
6 Remove component
7 Initialize project
8 Recover interrupted operation
9 Cleany maintenance / reset
10 Project doctor / repair
11 Rename or move an entry
12 Configure native flavors
0 Exit
All normal actions use the menu. The direct shortcut cleany maintenance opens option 9. Feature/init flags and the old feature/component subcommands are not accepted.
Generated architecture #
my_flutter_app/
├── android/
├── ios/
├── assets/
│ ├── images/
│ ├── icons/
│ └── translations/
│ ├── app_en.arb
│ └── app_ar.arb
├── config/flavors/
│ ├── dev.yaml
│ ├── uat.yaml
│ └── prod.yaml
├── lib/
│ ├── app/
│ │ ├── app.dart
│ │ ├── bootstrap.dart
│ │ ├── config/
│ │ │ ├── app_config.dart
│ │ │ ├── app_environment.dart
│ │ │ └── flavor_config.dart
│ │ ├── composition/feature_pages.dart
│ │ ├── di/injection.dart
│ │ └── router/
│ │ ├── app_router.dart
│ │ └── route_names.dart
│ ├── core/
│ │ ├── errors/
│ │ │ ├── failure.dart
│ │ │ └── error_reporter.dart
│ │ ├── network/
│ │ │ ├── api_endpoints.dart
│ │ │ ├── failure_mapper.dart
│ │ │ ├── dio/
│ │ │ │ ├── dio_client.dart
│ │ │ │ └── interceptors/auth_interceptor.dart
│ │ │ └── retrofit/home_api.dart
│ │ ├── localization/generated/
│ │ ├── storage/
│ │ ├── theme/
│ │ ├── constants/
│ │ ├── utils/
│ │ └── widgets/
│ ├── features/home/
│ │ ├── data/
│ │ │ ├── datasources/home_remote_data_source.dart
│ │ │ ├── models/home_model.dart
│ │ │ └── repositories/home_repository_impl.dart
│ │ ├── domain/
│ │ │ ├── entities/home_entity.dart
│ │ │ ├── repositories/home_repository.dart
│ │ │ └── usecases/get_home.dart
│ │ └── presentation/
│ │ ├── cubit/
│ │ │ ├── home_cubit.dart
│ │ │ └── home_state.dart
│ │ ├── pages/home_page.dart
│ │ └── widgets/
│ ├── components/user_card/
│ │ ├── cubit/
│ │ └── widgets/user_card_widget.dart
│ ├── main_dev.dart
│ ├── main_uat.dart
│ └── main_prod.dart
├── test/
├── integration_test/
├── .cleany/features.json
├── flavorizr.yaml
├── l10n.yaml
├── analysis_options.yaml
└── pubspec.yaml
This example selects Cubit and Retrofit. Bloc uses a bloc/ folder with event/state files. Direct Dio omits the Retrofit client. Components without state management have only their widget scaffold. Native folders are supplied by Flutter, not recreated by Cleany initialization.
Data flow and ownership #
API JSON → DataSource → Repository → Model → Entity → UseCase → Cubit/Bloc → UI
└── exception → Failure → Result
The datasource returns raw JSON and propagates exceptions. The repository decodes a Freezed model, constructs the Entity, and returns one Success/Failure result. Presentation consumes entities rather than transport models. Failures distinguish network, unauthorized, validation, business, server, and unexpected errors; adapt the business mapping to your backend.
Application services/repositories use lazy singletons inside an application GetIt scope. Controllers are factories owned by BlocProvider. All registrations live in the application composition root; the router calls page factories without importing controllers. Authored generated Dart files include purpose comments.
Menu guide #
Examples below show representative inputs; native identifiers, file lists, and diagnostic results depend on your project. Mutating source plans finish with 1 — Apply and validate or 2 — Cancel. Enter defaults to Cancel at review.
7 — Initialize project #
Choose this first in an uninitialized Flutter project:
Choose a number: 7
Detected production app id: com.example.playground
API provider: 1 # Retrofit over Dio; 2 selects direct Dio
Continue [2]: 1
Cleany resolves supported static Gradle properties and Apple project/xcconfig identifiers. If there are multiple candidates, select the production id; if unresolved, enter it. No platform script is executed just to discover the identifier.
| Environment | Application / bundle id |
|---|---|
| prod | com.example.playground |
| dev | com.example.playground.dev |
| uat | com.example.playground.uat |
Initialization adds the fixed architecture, required dependencies, localization, and public flavor configuration. Existing dependencies, comments, assets, overrides, main entrypoint, and analysis rules are preserved where possible. Existing lib/app or lib/core directories are protected from initialization overwrite. Use Doctor for supported repairs; older unrelated architectures need an explicit migration.
1 — Create feature #
Choose a number: 1
Name (snake_case): home
State management: 1 # Cubit; 2 selects Bloc
Location [1]: 1 # Default: lib/features/home
Data contract [1]: 2
Response field count (1 to 30): 3
Response field 1, lowerCamelCase:type:JSON key: userName:string:home
Nullable [1] (y/N): y
Response field 2, lowerCamelCase:type:JSON key: favourite:list<string>:favourite
Nullable [2] (y/N): y
Response field 3, lowerCamelCase:type:JSON key: age:int:age
Nullable [3] (y/N): y
Continue [2]: 1
Each field uses name:type:jsonKey. Supported types are string, int, double, bool, datetime, list<string>, and list<int>; type names are case insensitive. Nullable accepts y/n, yes/no, or legacy 2/1; Enter means No. Counts are 1–30. Names must be lowerCamelCase; field names and JSON keys must be unique. Invalid input is retried at the current question. Arabic/Persian digits are accepted in numeric choices.
After the last response field, Cleany opens review directly. It does not ask for a method, endpoint, or request data. The API scaffold defaults to GET and a path based on the feature name; adapt its data-layer API to your real backend. Library callers can supply advanced typed FeatureSpec request contracts.
Location choices:
| Choice | Example | Result |
|---|---|---|
| 1 — Default directory | name home |
lib/features/home |
| 2 — Custom directory inside lib | parent lib/modules/account, name auth |
lib/modules/account/auth |
| 3 — Inside an existing feature | parent auth, name profile |
<auth path>/subfeatures/profile |
Names use nonreserved snake_case and must not collide with existing public Dart symbols or registered entries. Paths remain inside lib.
2 — Create component #
Choose a number: 2
Name (snake_case): user_card
State management: 1 # Cubit; 2 = Bloc; 3 = no state management
Location [1]: 2
Parent directory (example: lib/shared/components): lib/shared/components
Continue [2]: 1
Creates lib/shared/components/user_card. Components contain a widget and optional controller/state files. They do not add feature routes, data/domain layers, or response-field prompts.
3 / 4 — List features / components #
Choose a number: 3
home · cubit · lib/features/home
Choose a number: 4
user_card · cubit · lib/shared/components/user_card
Lists the matching registered entry kind, its state-management style, and location. Missing/corrupt metadata can be inspected through Doctor.
5 / 6 — Remove feature / component #
Choose a number: 5 # 6 selects component removal
Select feature to remove: 1 # Select from the displayed entries
Continue [2]: 1
Review every planned removal. Removing a parent removes its registered descendants and the contents of its folder, including user edits inside that folder. External files require recorded ownership; matching names alone do not authorize deletion. Cleany updates DI, page factories, routes, owned API outputs, and the registry together. Remaining unrelated references cause staged analysis to fail before application.
8 — Recover interrupted operation #
Choose a number: 8
Recovery [2]: 1
Attempts restoration from the durable journal. Kernel locks are released when their process dies, and dead legacy PID locks are reclaimed automatically. Safe files are restored even if another file conflicts. Conflicting edits and backups are retained for resolution and a later recovery attempt; first save edits you want to keep before resolving them.
9 — Maintenance / reset #
cleany maintenance
Or choose 9 from the main menu:
| Subchoice | Example | Behavior |
|---|---|---|
| 1 — Clean abandoned local cache | Action 1, then Apply |
Removes marked project-local staging folders; preserves recovery journals/backups and global pub/Flutter caches |
| 2 — Archive and reset | Action 2, then Apply and validate |
Archives managed files under .cleany/backups/reset_<timestamp>/, then installs a fresh architecture and empty entry registry |
| 3 — Set command timeout | Action 3, timeout 600, then Apply |
Stores a 600-second deadline per command in .cleany/settings.json |
| 4 — Cancel | Action 4 |
Returns to the main menu |
Reset archives app/core, registered folders, and managed configuration, including their edits. Unrelated source/dependencies and native projects remain. Unrelated imports of removed entries can prevent validation; the original project is then preserved. Default command timeout is 300 seconds; accepted values are 5–3600.
10 — Project Doctor / repair #
Choose a number: 10
REPAIR ...missing registry, source, dependency, or binding...
NOTICE ...preserved edit or unsupported custom structure...
Continue [2]: 1
Doctor compares folders, the ownership registry, required dependency constraints, DI, page factories, and routes. It proposes specific supported repairs, archives corrupt registry contents, and can infer supported field contracts when rebuilding metadata. Edited files are preserved. Unsupported composition structures require manual resolution rather than guessed edits. All proposed repairs pass the same validation transaction.
11 — Rename or move an entry #
Choose a number: 11
Entry: 1
New name [home]: dashboard
Parent directory [lib/features]: lib/modules
Continue [2]: 1
Moves the entry to lib/modules/dashboard, updating known generated symbols, owned filenames, imports/exports/parts, DI, routes, child metadata, and registry paths. Backend API endpoint strings remain unchanged. References outside supported source roots or dynamic string references need manual review.
12 — Configure native flavors #
Choose a number: 12
Platforms: 1 # Select an existing platform, or All available
Continue [2]: 1
Stages only selected Android/iOS/macOS folders and runs the configured Flavorizr platform processors in isolation. Native files participate in validation, ownership, and recovery. Your platform SDKs, Ruby/Xcode dependencies, signing, icons, and device QA remain application-specific work.
0 — Exit #
Choose 0 to close the session. EOF cancels incomplete entry input. Failed operations offer retry or return to the main menu.
Run the generated application #
Set a public API URL in config/flavors/dev.yaml, or pass it at launch:
# Add --flavor dev after applying native flavor setup for that platform.
flutter run --target lib/main_dev.dart --dart-define=API_BASE_URL=https://api.example.com
Use main_uat.dart or main_prod.dart for those environments. UAT and production require HTTPS. YAML assets and dart-define values are extractable public configuration; keep privileged credentials on the backend. Dio can fetch session tokens at request time via TokenProvider and attaches them only to the trusted origin.
The generated main entrypoints are separate from an existing main.dart; choose the desired target explicitly. The initial UI is a scaffold: connect routes, forms, business rules, and backend contracts for your application.
Localization #
Edit assets/translations/app_en.arb and app_ar.arb. The official Flutter SDK flutter_localizations and gen-l10n produce source in lib/core/localization/generated/. The app follows the device language and supplies Material/Widgets/Cupertino delegates and Arabic RTL layout. No easy_localization dependency is added.
Safety and recovery #
- Build a plan and show source changes for review.
- Acquire a project lock and create a selective staging workspace.
- Resolve packages, run gen-l10n and builders, and analyze the result.
- Check original inputs and validated output fingerprints for changes.
- Apply the collected files with atomic replacement per file and a durable recovery journal.
The multi-file application is recoverable, not one indivisible filesystem operation. External observers can see intermediate states during application. Recovery preserves conflicting user edits and continues restoring safe records, including when another backup is damaged. Ctrl+C requests controlled cancellation; active commands have deadlines and command-tree termination.
Relevant source/configuration, declared assets/fonts, and selected native folders are copied using filesystem operations and streaming hashes. Build caches, Pods, unselected native folders, and unrelated root binaries are excluded. Abandoned marked staging folders are cleaned automatically. Unexpected output locations and changes during/after analysis fail explicitly rather than silently discarding generated files.
Commit .cleany/features.json; it records schema/template versions, contracts, paths, types, ownership, and hashes. Generated ignore entries exclude runtime cache/journal/backup files. Do not remove .cleany/operation.lock to bypass a live operation. Progress is shown in the terminal and recorded in .cleany/logs/latest.jsonl.
Limits and migration #
- One fixed template; existing 1.x layouts are not silently migrated by init.
- Pub workspaces and symlinked source paths are unsupported.
- AST edits support the fixed composition contracts and several function/list forms; arbitrary conditional DI or renamed composition entrypoints need manual integration.
- Native id discovery is static and conservative; dynamic scripts may require manual input.
- CLI field input supports flat response fields. Nested DTOs, envelopes, multipart, pagination, multiple operations, and path parameters require application code.
- Rename/move handles known symbols and URI directives in lib/test/integration_test/tool; runtime strings and external references need review.
- Memory holds changed file contents and fingerprint metadata. Very large resets/moves still need performance evaluation for the particular repository.
See CHANGELOG for the release summary and the usage guide for a guided walkthrough.
Library example #
package:cleany/cleany.dart exposes planning, transaction, recovery, and maintenance APIs. The runnable example prepares a plan using a disposable project and cleans it up; it does not alter your application:
dart run example/cleany_example.dart
For real applications, leave package installation, builders, and analysis enabled in GenerationTransaction.apply.
Development and release checks #
dart pub get
dart format --output=none --set-exit-if-changed lib bin test example
dart analyze --fatal-infos
dart test test/generator_test.dart test/advanced_test.dart
dart run example/cleany_example.dart
dart doc
dart pub outdated
dart pub publish --dry-run
Actual generated-app tests resolve Flutter dependencies and run builders, analysis, runtime tests, refactoring, repair, removal, reset, and native flavor configuration:
# macOS: full suite, including Apple native configuration
CLEANY_FLUTTER_INTEGRATION=true dart test test/generated_app_test.dart --concurrency=1
On Linux, set CLEANY_FLUTTER_INTEGRATION=true and select --name 'generated dio' to run the Dio fixture without Apple native configuration. On PowerShell, set $env:CLEANY_FLUTTER_INTEGRATION = 'true', then run dart test test/generated_app_test.dart --name 'generated dio' --concurrency=1. The complete native Apple configuration fixture requires macOS. CI uses stable toolchains and the minimum supported Dart SDK. Package review can additionally use pana on a disposable copy; pub.dev determines the final published score.
Local release audit #
The 2.0.0 local pana audit achieved 160/160, with 100% public API documentation, clean analysis, and current dependency support. See the dated report and verification details. pub.dev determines the final published score after upload.
License and support #
BSD 3-Clause; see LICENSE. Report reproducible problems through GitHub issues, including the Cleany/Flutter/Dart versions, selected menu action, and sanitized diagnostics.