coregen-cli 3.1.6__tar.gz

coregen_cli-3.1.6/PKG-INFO

@@ -0,0 +1,1211 @@
+Metadata-Version: 2.4
+Name: coregen-cli
+Version: 3.1.6
+Summary: A CLI to generate Flutter projects with DDD architecture
+Author-email: Lorenzo Busi <info@lorenzobusi.it>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+
+# 🚀 CoreGen
+
+**A CLI to generate and manage Flutter projects with DDD (Domain-Driven Design) architecture**
+
+[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
+[![Flutter](https://img.shields.io/badge/Flutter-Compatible-02569B.svg)](https://flutter.dev/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**Sito:** [coregen.dev](https://coregen.dev/) · **Repository:** [github.com/lorenzo9598/coregen](https://github.com/lorenzo9598/coregen)
+
+---
+
+## 📑 Table of Contents
+
+- [What is CoreGen?](#-what-is-coregen)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Available Commands](#-available-commands)
+  - [`create`](#coregen-create) - Create new project
+  - [`add-domain`](#coregen-add-domain) - Add domain entity (model + infrastructure)
+  - [`add-enum`](#coregen-add-enum) - Add domain enum
+  - [`add-page`](#coregen-add-page) - Add simple page
+  - [`add-component`](#coregen-add-component) - Add reusable component (form, list, single)
+  - [`list`](#coregen-list) - List project resources
+  - [`config`](#coregen-config) - Manage configuration
+- [Global Flags](#-global-flags)
+- [Configuration](#-configuration)
+- [Generated Architecture](#-generated-architecture)
+- [Core: value objects and errors](#core-value-objects-and-errors)
+- [Testing](#-testing)
+- [Troubleshooting](#-troubleshooting)
+
+---
+
+## 📖 What is CoreGen?
+
+CoreGen is a command-line tool that **automates Flutter project creation** following **Domain-Driven Design (DDD)** architecture best practices.
+
+Instead of manually creating dozens of files for each new feature (entity, repository, bloc, page, dto...), CoreGen generates them automatically with a consistent and professional structure.
+
+### 🎯 Problem It Solves
+
+Creating a new feature in a Flutter DDD project requires:
+- 📁 Creating 4+ folders (model, infrastructure, application, presentation)
+- 📄 Creating 10+ Dart files (entity, failure, repository interface, dto, bloc, event, state, page...)
+- ✏️ Writing boilerplate code for each file
+- 🔗 Updating the router with new routes
+- ⏱️ **Estimated time: 30-60 minutes per feature**
+
+With CoreGen:
+
+```bash
+coregen add-domain --name todo --fields "title:string,done:bool"
+coregen add-component --name todo_list --type list
+```
+
+**Time: 5 seconds** ⚡
+
+### 💡 Who It's For
+
+- **Flutter developers** using DDD/Clean Architecture
+- **Teams** wanting to standardize code structure
+- **Freelancers** wanting to speed up new project development
+- **Students** wanting to learn DDD architecture with practical examples
+
+---
+
+## 📦 Installation
+
+### Requirements
+
+- **Python 3.8+**
+- **Flutter SDK** (for generated projects)
+
+### Installation from Source (Recommended)
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/lorenzo9598/coregen.git
+cd coregen
+
+# 2. Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# or: venv\Scripts\activate  # Windows
+
+# 3. Install dependencies
+pip install -e .
+
+# 4. Verify installation
+coregen --help
+```
+
+### Installation via pip (when published)
+
+```bash
+pip install coregen-cli
+```
+
+### Verify Installation
+
+```bash
+coregen --help
+```
+
+Expected output:
+
+```
+Usage: coregen [OPTIONS] COMMAND [ARGS]...
+
+  🚀 CoreGen - Flutter DDD Project Generator
+  ...
+```
+
+---
+
+## 🚀 Quick Start
+
+### Scenario 1: New Project
+
+```bash
+# 1. Create a new Flutter project with DDD structure
+coregen create --name my_app
+
+# 2. Enter the project
+cd my_app
+
+# 3. Add a complete feature
+coregen add-domain --name todo --fields "title:string,done:bool,priority:int"
+coregen add-component --name todo_list --type list
+
+# 5. Run the project
+flutter run
+```
+
+### Scenario 2: Existing Project
+
+```bash
+# 1. Go to your existing Flutter project
+cd my_existing_flutter_app
+
+# 2. Add features
+coregen add-domain --name user --fields "name:string,email:string"
+coregen add-component --name user_list --type list
+```
+
+### Scenario 3: Preview Before Creating
+
+```bash
+# Use --dry-run to see what will be created without modifying anything
+coregen add-domain --name product --fields "name:string,price:double" --dry-run
+```
+
+---
+
+## 📋 Available Commands
+
+| Command         | Description                               | Typical Use       |
+| --------------- | ----------------------------------------- | ----------------- |
+| `create`        | Create new Flutter DDD project            | Project start     |
+| `add-domain`    | Add domain entity (model, infrastructure) | Shared domain model |
+| `add-enum`      | Add Dart enum under domain                | Types used in models |
+| `add-component` | Add component (form, list, single)        | UI + BLoC         |
+| `add-page`      | Add simple page                           | Static pages      |
+| `list`          | List pages (router) and domain models     | Overview          |
+| `config`        | Manage configuration                      | Customization     |
+
+---
+
+## 🔧 Command Details
+
+### `coregen create`
+
+**Creates a new Flutter project with complete DDD architecture.**
+
+#### Syntax
+
+```bash
+coregen create [OPTIONS]
+```
+
+#### Options
+
+| Option    | Type   | Required | Default | Description               |
+| --------- | ------ | -------- | ------- | ------------------------- |
+| `--name`  | string | ❌        | -       | Project name (snake_case) |
+| `--login` | flag   | ❌        | `false` | Include authentication    |
+
+#### Usage Modes
+
+**1. Complete command line:**
+
+```bash
+coregen create --name my_app --login
+```
+
+**2. Interactive mode** (if you don't specify --name):
+
+```bash
+coregen create
+```
+
+```
+Project name: my_app
+Does the project have login? [y/N]: y
+```
+
+#### Examples
+
+```bash
+# Basic project
+coregen create --name my_app
+
+# Project with authentication
+coregen create --name my_app --login
+
+# Interactive mode (asks for name and options)
+coregen create
+```
+
+#### Generated Structure
+
+```
+my_app/
+├── lib/
+│   ├── core/
+│   │   ├── model/              # Value objects, failures, errors
+│   │   │   ├── value_objects.dart
+│   │   │   ├── value_failures.dart
+│   │   │   └── value_validators.dart
+│   │   ├── infrastructure/     # Firebase modules, helpers
+│   │   │   ├── firebase_injectable_module.dart
+│   │   │   └── utils.dart
+│   │   └── presentation/       # Common widgets
+│   │       └── app_widget.dart
+│   ├── domain/                 # Domain entities (shared business entities)
+│   ├── features/               # Features (use cases)
+│   │   ├── home/
+│   │   │   └── presentation/
+│   │   │       └── home_page.dart
+│   │   └── splash/
+│   │       └── presentation/
+│   │           └── splash_page.dart
+│   ├── main.dart              # Entry point
+│   ├── injection.dart         # Dependency injection setup
+│   └── router.dart            # Routing with auto_route
+├── pubspec.yaml               # Flutter dependencies
+├── analysis_options.yaml
+└── ...
+```
+
+---
+
+### `coregen add-domain`
+
+**Adds a domain entity (model + infrastructure only).**
+
+Domain entities are shared business entities that can be used by multiple features. They do NOT include application or presentation layers.
+
+#### Syntax
+
+```bash
+coregen add-domain [OPTIONS]
+```
+
+#### Options
+
+| Option           | Type   | Required | Default     | Description                       |
+| ---------------- | ------ | -------- | ----------- | --------------------------------- |
+| `--name`         | string | ✅        | -           | Domain entity name                |
+| `--fields`       | string | ❌        | -           | Fields as name:type,name:type     |
+| `--folder`       | string | ❌        | from config | Domain folder (default: "domain") |
+| `--dry-run`      | flag   | ❌        | `false`     | Preview without creating          |
+| `--no-build`     | flag   | ❌        | `false`     | Skip flutter pub get              |
+| `--non-interactive` | flag | ❌     | `false`     | No field prompts; use `--fields` or id-only (CI/tools) |
+| `--project-path` | string | ❌        | `.`         | Project path                      |
+
+#### Usage Modes
+
+**Command line:**
+
+```bash
+coregen add-domain --name todo --fields "title:string,done:bool,priority:int"
+```
+
+**Interactive mode:**
+
+```bash
+coregen add-domain --name todo
+```
+
+```
+Domain entity name: todo
+Fields (name:type,name:type): title:string,done:bool,priority:int
+```
+
+#### Examples
+
+```bash
+# Domain entity with fields
+coregen add-domain --name todo --fields "title:string,done:bool,priority:int"
+
+# Interactive mode (will prompt for fields)
+coregen add-domain --name user
+
+# Preview what will be created
+coregen add-domain --name product --fields "name:string,price:double" --dry-run
+
+# Custom domain folder
+coregen add-domain --name note --fields "title:string" --folder shared/domain
+```
+
+#### Generated Structure
+
+```
+lib/domain/todo/
+├── model/
+│   ├── todo.dart
+│   ├── todo_failure.dart
+│   ├── i_todo_repository.dart
+│   ├── value_objects.dart
+│   └── value_validators.dart
+└── infrastructure/
+    ├── todo_dto.dart
+    ├── todo_service.dart
+    ├── todo_mapper.dart
+    └── todo_repository.dart
+```
+
+#### Field types and `--fields`
+
+Use `--fields` as a comma-separated list of `name:type`. **Commas inside angle brackets belong to the type** (e.g. `meta:Map<String,dynamic>,items:List<TodoItem>` is two fields).
+
+**Recommended order:** create enums with `add-enum` and any **referenced domain entities** before an entity that uses them in `List<Other>`, `Map<String, Other>`, or a bare `Other` field—CoreGen validates types against files under your configured domain folder.
+
+| Category | Examples in `--fields` | Generated domain usage |
+| -------- | ------------------------ | ------------------------ |
+| Primitives | `title:string`, `count:int`, `price:double`, `done:bool`, `at:datetime` | Wrapped value objects where applicable (`String` → `Title`-style VO) |
+| Nullable | `subtitle:string?`, `note:Note?`, `tags:List<String>?` | `Option<T>` or nullable collections per generator rules |
+| `UniqueId` | `id` is auto-added; optional `UniqueId` fields | Known value object |
+| Collections | `tags:List<String>`, `ids:Set<int>`, `scores:Map<String,int>`, `data:Map<String,dynamic>` | `List` / `Set` / `Map` with validated inner types |
+| Domain model | `author:User` (PascalCase, must exist) | Nested entity + mapper/DTO wiring |
+| Enum | `status:OrderStatus` (PascalCase; use `add-enum` first) | Dart enum + serialization mapping |
+
+The same type grammar applies to **`add-component --type form --fields "..."`** when you pass inline fields instead of sourcing them from a domain model.
+
+`add-domain` also regenerates `lib/core/errors/error_localizer.dart` so each entity’s `{Name}Failure` gets a matching `localize{Name}Failure` helper (see [Core: value objects and errors](#core-value-objects-and-errors)).
+
+---
+
+### `coregen add-enum`
+
+**Adds a Dart enum file** under `lib/<domain_folder>/enums/` so you can reference it from `add-domain --fields`.
+
+#### Syntax
+
+```bash
+coregen add-enum [OPTIONS]
+```
+
+#### Options
+
+| Option           | Type   | Required | Default     | Description |
+| ---------------- | ------ | -------- | ----------- | ----------- |
+| `--name`         | string | ✅        | -           | Enum name (PascalCase, e.g. `OrderStatus`) |
+| `--values`       | string | ❌        | -           | Comma-separated values (e.g. `pending,active,done`) |
+| `--folder`       | string | ❌        | from config | Domain root folder |
+| `--dry-run`      | flag   | ❌        | `false`     | Preview without creating |
+| `--force`        | flag   | ❌        | `false`     | Overwrite existing file without prompt |
+| `--project-path` | string | ❌        | `.`         | Project path |
+
+#### Example
+
+```bash
+coregen add-enum --name OrderStatus --values "pending,shipped,delivered"
+coregen add-domain --name order --fields "id:string,status:OrderStatus,total:double"
+```
+
+---
+
+### `coregen add-page`
+
+**Adds a simple page without business logic.**
+
+Ideal for static pages like About, Settings, Privacy Policy, etc.
+
+#### Syntax
+
+```bash
+coregen add-page [OPTIONS]
+```
+
+#### Options
+
+| Option           | Type   | Required | Default     | Description              |
+| ---------------- | ------ | -------- | ----------- | ------------------------ |
+| `--name`         | string | ✅        | -           | Page name                |
+| `--folder`       | string | ❌        | from config | Destination folder       |
+| `--dry-run`      | flag   | ❌        | `false`     | Preview without creating |
+| `--no-build`     | flag   | ❌        | `false`     | Skip flutter pub get     |
+| `--project-path` | string | ❌        | `.`         | Project path             |
+
+#### Usage Modes
+
+**Command line:**
+
+```bash
+coregen add-page --name settings
+```
+
+**Interactive mode:**
+
+```bash
+coregen add-page
+```
+
+```
+Page name: settings
+```
+
+#### Examples
+
+```bash
+# Settings page
+coregen add-page --name settings
+
+# About page with preview
+coregen add-page --name about --dry-run
+
+# Page in specific folder
+coregen add-page --name privacy --folder pages
+```
+
+#### Generated Structure
+
+```
+lib/features/settings/
+└── settings_page.dart
+```
+
+**Also updates:**
+- `lib/router.dart` - Adds the new route
+
+---
+
+### `coregen add-component`
+
+**Adds a reusable component with optional BLoC.**
+
+Supports three types: single (single item), list (list with CRUD), and form (form with validation).
+
+#### Syntax
+
+```bash
+coregen add-component [OPTIONS]
+```
+
+#### Options
+
+| Option       | Type   | Required | Default               | Description                          |
+| ------------ | ------ | -------- | --------------------- | ------------------------------------ |
+| `--name`     | string | ✅        | -                     | Component name                       |
+| `--type`     | choice | ❌        | -                     | Type: `form`, `list`, or `single`    |
+| `--fields`   | string | ❌        | -                     | Form fields (requires `--type form`) |
+| `--domain-model` | string | ❌     | -                     | Domain entity file stem, or `none` (skips model prompt; non-interactive) |
+| `--use-all-model-fields` | flag | ❌ | `false` | With form + domain model, include every field (skip selection prompt) |
+| `--folder`   | string | ❌        | from config         | Destination folder (e.g. `shared/widgets`) |
+| `--dry-run`  | flag   | ❌        | `false`               | Preview without creating             |
+| `--no-build` | flag   | ❌        | `false`               | Skip flutter pub get                 |
+| `--project-path` | string | ❌    | `.`                   | Project path                         |
+
+#### Three Component Types
+
+**1. Single Component** (`--type single` or default) - Widget that displays a single item loaded by ID:
+
+```bash
+coregen add-component --name user_card
+# or
+coregen add-component --name user_card --type single
+```
+
+**2. List Component** (`--type list`) - Widget that displays a list of items with complete CRUD operations:
+
+```bash
+coregen add-component --name todo_list --type list
+```
+
+**3. Form Component** (`--type form`) - Form with validation and field management:
+
+```bash
+coregen add-component --name login --type form --fields "email:string,password:string"
+```
+
+#### Usage Modes
+
+**Command line:**
+
+```bash
+# Single component (default)
+coregen add-component --name user_card
+
+# List component
+coregen add-component --name todo_list --type list
+
+# Form component
+coregen add-component --name login --type form --fields "email:string,password:string"
+```
+
+**Interactive mode:**
+
+```bash
+coregen add-component
+```
+
+```
+Component name: todo_list
+Select component type:
+  1. Single item (loads one item by ID)
+  2. List (shows all items with CRUD operations)
+  3. Form (form with validation)
+Type (1-3): 2
+```
+
+#### Examples
+
+```bash
+# Single component (default)
+coregen add-component --name user_card
+
+# List component with complete CRUD
+coregen add-component --name todo_list --type list
+
+# Form component with fields
+coregen add-component --name login --type form --fields "email:string,password:string"
+
+# Component in specific folder
+coregen add-component --name search_bar --folder shared/widgets
+
+# Registration form
+coregen add-component --name registration --type form --fields "name:string,email:string,password:string"
+```
+
+#### Generated Structure
+
+**Single Component:**
+
+```
+lib/user_card/
+├── application/
+│   ├── user_card_bloc.dart
+│   ├── user_card_event.dart
+│   └── user_card_state.dart
+└── presentation/
+    └── user_card_component.dart
+```
+
+**List Component:**
+
+```
+lib/todo_list/
+├── application/
+│   ├── todo_list_bloc.dart      # BLoC with getAll, create, update, delete
+│   ├── todo_list_event.dart      # loadRequested, createRequested, updateRequested, deleteRequested
+│   └── todo_list_state.dart      # initial, loading, loaded(List<Model>), error
+└── presentation/
+    └── todo_list_component.dart   # Widget with ListView and CRUD operations
+```
+
+**Form Component:**
+
+```
+lib/login/
+├── application/
+│   ├── login_form_bloc.dart
+│   ├── login_form_event.dart
+│   └── login_form_state.dart
+└── presentation/
+    └── login_component.dart
+```
+
+---
+
+<!-- DEPRECATED: This command has been removed from the CLI but code is maintained for backward compatibility -->
+<!-- ### `coregen add-drawer-item` (DEPRECATED)
+
+**Adds an item to the drawer (side menu) navigation.**
+
+Creates the page, drawer (if it doesn't exist) and configures everything automatically.
+
+**⚠️ DEPRECATED**: This command has been removed. Use `add-page` for simple pages or `add-component` for more complex navigation.
+
+#### Sintassi
+
+```bash
+coregen add-drawer-item [OPTIONS]
+```
+
+#### Opzioni
+
+| Opzione          | Tipo   | Obbligatorio | Default | Descrizione           |
+| ---------------- | ------ | ------------ | ------- | --------------------- |
+| `--name`         | string | ✅            | -       | Nome dell'item        |
+| `--dry-run`      | flag   | ❌            | `false` | Preview senza creare  |
+| `--no-build`     | flag   | ❌            | `false` | Salta flutter pub get |
+| `--project-path` | string | ❌            | `.`     | Path al progetto      |
+
+#### Modalità di Utilizzo
+
+**Riga di comando:**
+
+```bash
+coregen add-drawer-item --name settings
+```
+
+**Modalità interattiva:**
+
+```bash
+coregen add-drawer-item
+```
+
+```
+Drawer item name: settings
+```
+
+#### Esempi
+
+```bash
+# Aggiungi settings al drawer
+coregen add-drawer-item --name settings
+
+# Aggiungi profile
+coregen add-drawer-item --name profile
+
+# Preview
+coregen add-drawer-item --name help --dry-run
+```
+
+#### Cosa Viene Generato/Modificato
+
+1. ✅ Crea `lib/<nome>/presentation/<nome>_page.dart`
+2. ✅ Crea/Aggiorna `lib/core/presentation/app_drawer.dart`
+3. ✅ Aggiorna `lib/features/home/home_page.dart` (aggiunge drawer)
+4. ✅ Aggiorna `lib/router.dart`
+
+-->
+
+---
+
+<!-- DEPRECATED: This command has been removed from the CLI but code is maintained for backward compatibility -->
+<!-- ### `coregen add-bottom-nav-item` (DEPRECATED)
+
+**Adds a tab to the bottom navigation bar.**
+
+Creates the screen and configures the bottom navigation automatically.
+
+**⚠️ DEPRECATED**: This command has been removed. Use `add-page` for simple pages or `add-component` for more complex navigation.
+
+#### Sintassi
+
+```bash
+coregen add-bottom-nav-item [OPTIONS]
+```
+
+#### Opzioni
+
+| Opzione          | Tipo   | Obbligatorio | Default | Descrizione           |
+| ---------------- | ------ | ------------ | ------- | --------------------- |
+| `--name`         | string | ✅            | -       | Nome del tab          |
+| `--dry-run`      | flag   | ❌            | `false` | Preview senza creare  |
+| `--no-build`     | flag   | ❌            | `false` | Salta flutter pub get |
+| `--project-path` | string | ❌            | `.`     | Path al progetto      |
+
+#### Modalità di Utilizzo
+
+**Riga di comando:**
+
+```bash
+coregen add-bottom-nav-item --name search
+```
+
+**Modalità interattiva:**
+
+```bash
+coregen add-bottom-nav-item
+```
+
+```
+Tab name: search
+```
+
+#### Esempi
+
+```bash
+# Aggiungi tab search
+coregen add-bottom-nav-item --name search
+
+# Aggiungi tab favorites
+coregen add-bottom-nav-item --name favorites
+
+# Aggiungi tab profile
+coregen add-bottom-nav-item --name profile
+```
+
+#### Cosa Viene Generato/Modificato
+
+1. ✅ Crea `lib/features/home/<nome>_screen.dart`
+2. ✅ Crea/Aggiorna `lib/core/presentation/bottom_nav_bar.dart`
+3. ✅ Aggiorna `lib/features/home/home_page.dart` (aggiunge BottomNavigationBar)
+
+-->
+---
+
+### `coregen list`
+
+**Lists pages and domain models in the project.**
+
+Shows all pages parsed from `router.dart` and all domain models from the `domain/` folder.
+
+#### Syntax
+
+```bash
+coregen list [OPTIONS]
+```
+
+#### Options
+
+| Option           | Type   | Required | Default | Description  |
+| ---------------- | ------ | -------- | ------- | ------------ |
+| `--project-path` | string | ❌        | `.`     | Project path |
+
+#### Examples
+
+```bash
+# List pages and models
+coregen list
+```
+
+#### Example Output
+
+```
+╭──────────────────────╮
+│ 📋 Project: my_app   │
+╰──────────────────────╯
+
+📄 Pages:
+   /home          → HomePage        (lib/features/home/home_page.dart)
+   /              → SplashPage      (lib/features/splash/splash_page.dart)
+   /settings      → SettingsPage     (lib/features/settings/settings_page.dart)
+
+📦 Domain Models:
+   todo           (lib/domain/todo/model/todo.dart)
+   user           (lib/domain/user/model/user.dart)
+```
+
+📦 Features:
+todo/
+├── model/
+│   ├── todo
+│   └── todo_failure
+├── application/
+│   └── todo_bloc
+└── presentation/
+    └── todo_page
+
+user/
+├── model/
+│   ├── user
+│   └── user_failure
+...
+
+📄 Pages:
+   settings/ (1 file)
+   about/ (1 file)
+
+🧩 Components:
+   user_card/ (standard)
+   login/ (form)
+
+🛤️  Routes:
+   /home           → HomePage
+   /todo           → TodoPage
+   /settings       → SettingsPage
+   /user           → UserPage
+```
+
+---
+
+### `coregen config`
+
+**Manages CoreGen configuration.**
+
+Allows viewing or creating the configuration file.
+
+#### Syntax
+
+```bash
+coregen config [OPTIONS]
+```
+
+#### Options
+
+| Option           | Type   | Description                |
+| ---------------- | ------ | -------------------------- |
+| `--show`         | flag   | Show current configuration |
+| `--init`         | flag   | Create configuration file  |
+| `--project-path` | string | Project path               |
+
+#### Examples
+
+```bash
+# Show current configuration
+coregen config --show
+
+# Create configuration file
+coregen config --init
+```
+
+#### Output --show
+
+```
+╭─────────────────────── ⚙️  Configuration ────────────────────────╮
+│ ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓                         │
+│ ┃ Setting             ┃ Value         ┃                         │
+│ ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩                         │
+│ │ Feature Folder      │ features      │                         │
+│ │ Component Folder    │ components    │                         │
+│ │ Page Folder         │               │                         │
+│ │ Use BLoC            │ ✅            │                         │
+│ │ Use Freezed         │ ✅            │                         │
+│ │ Auto Build Runner   │ ✅            │                         │
+│ └─────────────────────┴───────────────┘                         │
+╰─────────────────────────────────────────────────────────────────╯
+
+📄 Project config: /path/to/project/coregen.yaml
+```
+
+---
+
+## 🏃 Global Flags
+
+These flags are available for all `add-*` commands:
+
+| Flag             | Description                               | Example                 |
+| ---------------- | ----------------------------------------- | ----------------------- |
+| `--dry-run`      | Preview without creating files            | `--dry-run`             |
+| `--no-build`     | Skip `flutter pub get` and `build_runner` | `--no-build`            |
+| `--project-path` | Specify project path                      | `--project-path ../app` |
+
+### --dry-run Example
+
+```bash
+$ coregen add-domain --name todo --fields "title:string" --dry-run
+$ coregen add-component --name todo_list --type list --dry-run
+```
+
+Output:
+
+```
+╭──────────────────────────╮
+│ 🔍 DRY-RUN MODE          │
+│ No files will be created │
+╰──────────────────────────╯
+
+🔧 Would add feature: todo
+   Fields: id:string
+
+📁 lib/todo/
+├── 📁 model/
+│   ├── 📄 todo.dart
+│   ├── 📄 todo_failure.dart
+│   ├── 📄 i_todo_repository.dart
+│   └── ...
+├── 📁 infrastructure/
+│   └── ...
+├── 📁 application/
+│   └── ...
+└── 📁 presentation/
+    └── 📄 todo_page.dart
+
+📝 Would update: lib/router.dart
+
+──────────────────────────────────────────────────
+ℹ️  Run without --dry-run to create these files
+```
+
+### --no-build Example
+
+```bash
+# Faster: skip pub get and build_runner
+coregen add-domain --name todo --fields "title:string" --no-build
+coregen add-component --name todo_list --type list --no-build
+
+# Then run manually when you want
+flutter pub get
+dart run build_runner build --delete-conflicting-outputs
+```
+
+---
+
+## ⚙️ Configuration
+
+### Configuration Priority
+
+CoreGen loads configuration from multiple sources (in priority order):
+
+1. **🔴 CLI Flags** (highest priority) - `--folder features`
+2. **🟠 `coregen.yaml`** in project
+3. **🟡 `~/.coregenrc`** global (home directory)
+4. **🟢 Defaults** (lowest priority)
+
+### Create Configuration
+
+```bash
+# Create coregen.yaml in project
+coregen config --init
+```
+
+### coregen.yaml Example
+
+```yaml
+# 📁 Default folders for generated code
+defaults:
+  feature_folder: "features"     # lib/features/todo/
+  domain_folder: "domain"         # lib/domain/note/ (shared entities)
+  component_folder: "features/components" # lib/features/components/user_card/
+  auto_run_build_runner: true    # Runs build_runner after generation
+
+# 🎨 UI Configuration (for future reference)
+styling:
+  primary_color: "#2196F3"
+  secondary_color: "#FF9800"
+```
+
+### ~/.coregenrc Example (Global)
+
+```yaml
+# Global configuration for all projects
+defaults:
+  feature_folder: "features"
+  auto_run_build_runner: false  # Disable for all projects
+```
+
+---
+
+## 🏗️ Generated Architecture
+
+CoreGen generates projects following **DDD (Domain-Driven Design)** architecture with layer separation:
+
+```
+lib/
+├── core/                        # 🔧 CORE - Shared code
+│   ├── model/                   # Value objects, validation failures, errors
+│   │   ├── value_objects.dart
+│   │   ├── failures.dart        # ValueFailure<T> (Freezed)
+│   │   ├── errors.dart          # UnexpectedValueError
+│   │   └── value_validators.dart
+│   ├── errors/
+│   │   └── error_localizer.dart # Maps domain *Failure to UI strings
+│   ├── infrastructure/          # DI modules, helpers
+│   │   └── firebase_injectable_module.dart
+│   └── presentation/            # Common widgets
+│       └── app_widget.dart
+│
+├── domain/                      # 🏛️ DOMAIN ENTITIES - Shared entities
+│   ├── auth/                    # Auth entity (shared)
+│   │   ├── model/               # Entity, failures, repository interface
+│   │   │   ├── user.dart
+│   │   │   ├── user_profile.dart
+│   │   │   └── i_auth_facade.dart
+│   │   └── infrastructure/      # Repository implementation, DTOs
+│   │       ├── firebase_auth_facade.dart
+│   │       └── user_profile_repository.dart
+│   │
+│   └── note/                    # Example: Note entity (shared)
+│       ├── model/
+│       │   ├── note.dart
+│       │   └── i_note_repository.dart
+│       └── infrastructure/
+│           └── note_repository.dart
+│
+├── features/                    # 📦 FEATURES - Specific use cases
+│   ├── auth/                    # Auth feature (complete use case)
+│   │   ├── application/         # ⚙️ APPLICATION LAYER
+│   │   │   ├── auth_bloc.dart
+│   │   │   ├── auth_event.dart
+│   │   │   └── auth_state.dart
+│   │   └── presentation/        # 🎨 PRESENTATION LAYER
+│   │       └── login_page.dart
+│   │
+│   └── notes/                    # Example feature "note management"
+│       │                          # (uses domain/note)
+│       ├── application/         # ⚙️ APPLICATION LAYER
+│       │   ├── notes_bloc.dart      # BLoC (logic)
+│       │   ├── notes_event.dart     # Events
+│       │   └── notes_state.dart     # States
+│       │
+│       └── presentation/        # 🎨 PRESENTATION LAYER
+│           └── notes_page.dart      # UI
+│
+├── shared/                      # 🧩 SHARED - Shared components
+│   └── widgets/
+│
+├── main.dart                    # Entry point
+├── injection.dart               # 💉 Dependency Injection
+└── router.dart                  # 🛤️ Routing (auto_route)
+```
+
+### Why DDD?
+
+| Benefit             | Description                              |
+| ------------------- | ---------------------------------------- |
+| **Testability**     | Each layer is isolated and testable      |
+| **Maintainability** | Organized and predictable code           |
+| **Scalability**     | Easy to add new features                 |
+| **Team**            | Multiple developers can work in parallel |
+
+---
+
+## Core: value objects and errors
+
+Generated projects share a small **core** model for validated inputs and user-visible failures.
+
+| File | Role |
+| ---- | ---- |
+| `lib/core/model/value_validators.dart` | Pure functions returning `Either<ValueFailure<T>, T>` (e.g. max length, not empty). Composed with `flatMap` inside each domain value object factory. |
+| `lib/core/model/value_objects.dart` | Abstract `ValueObject<T>` holding `Either<ValueFailure<T>, T>`, plus helpers like `getOrCrash()`, `failureOrUnit`, and shared types (`UniqueId`, …). |
+| `lib/core/model/failures.dart` | Freezed `ValueFailure<T>` variants (**validation** errors: empty string, list too long, invalid email, …). Extension `ValueFailureX` can expose default `title` / `message` strings. |
+| `lib/core/model/errors.dart` | `UnexpectedValueError` — thrown when code calls `getOrCrash()` on an invalid value object. |
+| `lib/core/errors/error_localizer.dart` | Maps each domain entity’s `{Entity}Failure` (in `lib/.../model/*_failure.dart`) to a user-facing string via `localize{Entity}Failure`. Regenerated when you add domain entities; optional `localizeAuthFailure` when auth exists. Template comments show how to swap strings for **l10n**. |
+
+**Domain `*Failure` vs `ValueFailure`:** `{Entity}Failure` (e.g. `TodoFailure`) models **business / IO** problems (not found, permission denied, …) used by repositories and BLoCs. `ValueFailure` models **invalid field input** at the value-object layer.
+
+---
+
+## 📚 Flutter Generated Dependencies
+
+Generated projects use these standard Flutter dependencies:
+
+| Package           | Purpose                | Link                                                |
+| ----------------- | ---------------------- | --------------------------------------------------- |
+| `flutter_bloc`    | State management       | [pub.dev](https://pub.dev/packages/flutter_bloc)    |
+| `freezed`         | Immutable classes      | [pub.dev](https://pub.dev/packages/freezed)         |
+| `injectable`      | Dependency injection   | [pub.dev](https://pub.dev/packages/injectable)      |
+| `auto_route`      | Declarative routing    | [pub.dev](https://pub.dev/packages/auto_route)      |
+| `dartz`           | Functional programming | [pub.dev](https://pub.dev/packages/dartz)           |
+| `json_annotation` | JSON serialization     | [pub.dev](https://pub.dev/packages/json_annotation) |
+
+---
+
+## 🧪 Testing
+
+```bash
+# Activate virtual environment
+source venv/bin/activate
+
+# Run all tests
+pytest tests/ -v
+
+# Only fast tests (without E2E)
+pytest tests/test_basic.py tests/test_integration.py -v
+
+# Only E2E tests (requires Flutter SDK installed)
+pytest tests/test_e2e_flutter.py -v
+
+# With coverage
+pytest tests/ --cov=. --cov-report=html
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### "Command not found: coregen"
+
+```bash
+# Make sure you installed correctly
+pip install -e .
+
+# Or use python directly
+python coregen.py --help
+```
+
+### `coregen --help` shows only "create" (no add-domain, add-page, etc.)
+
+You are using an **old or different** installation of CoreGen that only exposes the `create` command. The full CLI is a **group** of commands: `create`, `add-domain`, `add-enum`, `add-page`, `add-component`, `list`, `config`.
+
+**Fix:**
+
+1. Check which executable runs: `which coregen`
+2. Use the CLI from this repo:
+   ```bash
+   cd /path/to/coregen   # this repo root
+   python3 coregen.py --help
+   ```
+   You should see "Usage: coregen [OPTIONS] **COMMAND** [ARGS]..." and the list of commands.
+3. Either:
+   - **Option A**: Remove or rename the old `coregen` from your PATH, then install from this repo: `pip install -e .` (requires pip ≥ 21.3), or
+   - **Option B**: Add an alias so the repo’s CLI wins:
+     ```bash
+     alias coregen='python3 /path/to/coregen/coregen.py'
+     ```
+     (Replace `/path/to/coregen` with the real path to this repo.)
+
+### "Not a valid Flutter project"
+
+```bash
+# CoreGen requires pubspec.yaml and lib/
+# Make sure you're in a valid Flutter project
+ls pubspec.yaml lib/
+```
+
+### "rich import error" in IDE
+
+The IDE might not recognize the virtual environment. Solution:
+1. `Cmd+Shift+P` → "Python: Select Interpreter"
+2. Select `./venv/bin/python`
+
+### build_runner slow
+
+```bash
+# Use --no-build to skip build_runner
+coregen add-domain --name todo --fields "title:string" --no-build
+coregen add-component --name todo_list --type list --no-build
+
+# Run build_runner once at the end
+dart run build_runner build --delete-conflicting-outputs
+```
+
+### Dart compilation errors
+
+After generating code, run:
+
+```bash
+flutter pub get
+dart run build_runner build --delete-conflicting-outputs
+```
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create branch: `git checkout -b feature/new-feature`
+3. Commit: `git commit -m 'Add new feature'`
+4. Push: `git push origin feature/new-feature`
+5. Open Pull Request
+
+### Project Structure
+
+```
+coregen/
+├── coregen.py              # Main CLI
+├── generators/
+│   ├── helpers/                # Helper functions
+│   │   ├── config.py           # Configuration management
+│   │   └── project.py          # Project validation
+│   └── static/templates/       # Jinja2 templates
+├── tests/                      # Test suite
+└── docs/                       # Documentation
+```
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE)
+
+---
+
+## 👨‍💻 Author
+
+**Lorenzo Busi** - [GetAutomation](https://getautomation.it)
+
+---
+
+## 🙏 Acknowledgments
+
+- [Click](https://click.palletsprojects.com/) - CLI framework
+- [Jinja2](https://jinja.palletsprojects.com/) - Template engine
+- [Rich](https://rich.readthedocs.io/) - Terminal formatting
+- [Flutter](https://flutter.dev/) - UI framework
+- [Reso Coder](https://resocoder.com/) - DDD architecture inspiration
+
+---
+
+<p align="center">
+  <i>Generated with ❤️ by CoreGen</i>
+</p>