digraph when_to_use {
    "Need to generate code in Zuraffa project?" [shape=diamond, style=filled, fillcolor=lightgreen];
    "Use Zuraffa CLI" [shape=box, style=filled, fillcolor=lightblue];

    "Need to generate code in Zuraffa project?" -> "Use Zuraffa CLI" [label="ALWAYS"];
}

# Create entity with fields (NEVER create manually)
zfa entity create -n User --field name:String --field email:String?

# Create enum
zfa entity enum -n Status --value active,inactive,pending

# Create entity from JSON
zfa entity from-json user_data.json

# List entities
zfa entity list

# Build generated code (NEVER run build_runner directly)
zfa build
zfa build --watch
zfa build --clean

# Generate EVERYTHING - domain, data, presentation, tests, DI
zfa generate Product \
  --methods=get,getList,create,update,delete,watchList \
  --data \
  --vpc \
  --state \
  --cache \
  --di \
  --test

# That's it - one command, complete feature

# Generate UseCases for entity (repository auto-created)
zfa generate Product --methods=get,getList,create,update,delete,watchList

# Custom UseCase with repository
zfa generate SearchProduct --domain=search --repo=Product --params=Query --returns=List<Product>

# Custom UseCase with service (for non-entity operations)
zfa generate ProcessPayment --domain=payment --service=Payment --params=PaymentRequest --returns=PaymentResult

# Orchestrator (compose UseCases)
zfa generate ProcessCheckout --domain=checkout --usecases=ValidateCart,ProcessPayment --params=Request --returns=Order

# Background UseCase (CPU-intensive)
zfa generate ProcessImages --type=background --params=ImageBatch --returns=ProcessedImage

# Sync UseCase (validation, calculations)
zfa generate ValidateEmail --type=sync --params=String --returns=bool

# Generate DataRepository + DataSource
zfa generate Product --methods=get,getList,create --data

# With caching
zfa generate Product --methods=get,getList --data --cache --cache-policy=daily

# With GraphQL
zfa generate Product --methods=get,create --data --gql --gql-returns="id,name,price"

# Append method to existing repository
zfa generate WatchProduct --domain=product --repo=Product --params=String --returns=Stream<Product> --type=stream --append

# Generate View + Presenter + Controller
zfa generate Product --methods=get,getList,create --vpc

# Generate with State object
zfa generate Product --methods=get,getList,create --vpcs

# Generate Presenter + Controller only (preserve custom View)
zfa generate Product --methods=get,getList --pc

# Generate Presenter + Controller + State (preserve custom View)
zfa generate Product --methods=get,getList --pcs

# Generate unit tests
zfa generate Product --methods=get,create,update --test

# Generate mock data
zfa generate Product --mock

# Mock data only
zfa generate Product --mock-data-only

# Generate DI files
zfa generate Product --methods=get,getList --data --di

# Use mock datasource in DI
zfa generate Product --methods=get,getList --data --mock --di --use-mock

# With cache initialization
zfa generate Config --methods=get --data --cache --di

lib/src/domain/entities/{entity_snake}/{entity_snake}.dart

lib/src/domain/entities/product/product.dart

zfa entity create -n Product --field name:String --field price:double

lib/src/
├── domain/                    # Pure Dart business logic
│   ├── entities/              # Business objects (NEVER create manually)
│   ├── repositories/          # Repository interfaces (contracts)
│   ├── services/              # Service interfaces (alternative to repos)
│   └── usecases/              # Business operations
│       ├── {entity}/          # Entity-specific usecases
│       └── {domain}/          # Domain-specific usecases
├── data/                      # External dependencies
│   ├── data_sources/          # Data source implementations
│   │   └── {entity}/
│   │       ├── graphql/       # GraphQL operations
│   │       ├── {entity}_data_source.dart
│   │       └── {entity}_remote_data_source.dart
│   ├── providers/             # Service provider implementations
│   └── repositories/          # Repository implementations
├── presentation/              # UI layer (use --vpc)
│   └── pages/
│       └── {entity}/
│           ├── {entity}_view.dart
│           ├── {entity}_presenter.dart
│           ├── {entity}_controller.dart
│           └── {entity}_state.dart
└── di/                        # Dependency injection
    ├── datasources/
    ├── repositories/
    ├── usecases/
    └── index.dart

# One command - generates EVERYTHING
zfa generate Product \
  --methods=get,getList,create,update,delete,watchList \
  --data \
  --vpc \
  --state \
  --cache \
  --di \
  --test

# Build the generated entities
zfa build

# That's it - feature complete

# 1. Create entity
zfa entity create -n Product --field name:String --field price:double
zfa build

# 2. Generate domain + data layer
zfa generate Product --methods=get,getList,create,update,delete --data

# 3. Generate UI layer
zfa generate Product --methods=get,getList,create --vpc --state

# 4. Implement DataSource (manual - only this part)
# 5. Register with DI
zfa generate Product --methods=get,getList --data --di

# 1. Create atomic UseCases
zfa generate ValidateCart --repo=Cart --domain=checkout --params=CartId --returns=bool
zfa generate CreateOrder --repo=Order --domain=checkout --params=OrderData --returns=Order
zfa generate ProcessPayment --service=Payment --domain=checkout --params=PaymentData --returns=Receipt

# 2. Orchestrate them
zfa generate ProcessCheckout \
  --usecases=ValidateCart,CreateOrder,ProcessPayment \
  --domain=checkout \
  --params=CheckoutRequest \
  --returns=Order

# 3. Generate UI for orchestrator
zfa generate ProcessCheckout --domain=checkout --vpc --state

# Add watch method to existing entity
zfa generate WatchProduct --domain=product --repo=Product --params=String --returns=Stream<Product> --type=stream --append

# If UI exists, regenerate presenter/controller
zfa generate Product --methods=watch --pc --force

{
  "name": "Product",
  "methods": ["get", "getList", "create", "update", "delete", "watchList"],
  "data": true,
  "vpc": true,
  "state": true,
  "cache": true,
  "cachePolicy": "daily",
  "di": true,
  "test": true
}

{
  "name": "SearchProduct",
  "domain": "search",
  "repo": "Product",
  "params": "Query",
  "returns": "List<Product>",
  "type": "usecase"
}

Error: Entity 'Product' not found at expected path

zfa entity create -n Product --field name:String
zfa build

zfa generate Product --methods=get,getList --force

zfa generate Product --methods=get --dry-run --format=json

zfa generate SparkSearch \
  --type=stream \
  --variants=Barcode,Url,Text \
  --domain=search \
  --repo=Search \
  --params=Spark \
  --returns=Listing

zfa generate Order --methods=get --gql \
  --gql-returns="id,createdAt,customer{id,name},items{id,quantity,price}"

zfa generate ValidateEmail --type=sync --params=String --returns=bool

class ValidateEmailUseCase extends SyncUseCase<bool, String> {
  @override
  bool execute(String email) {
    return RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$').hasMatch(email);
  }
}