wlmaker 1.7.0 → 1.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1 +1,749 @@
1
- # wlmaker-cli
1
+ # Guía de Uso de wlmaker
2
+
3
+ > **Para nuevos desarrolladores.** Aprendé a usar `wlmaker` para generar código Flutter/Dart
4
+ > en monorepos Melos con Clean Architecture, BLoC, Freezed y Widgetbook.
5
+
6
+ ---
7
+
8
+ ## 1. ¿Qué es wlmaker?
9
+
10
+ **wlmaker** (alias: `wl`) es una CLI que **scaffoldea código Flutter/Dart** desde la terminal.
11
+ Está pensada para equipos que trabajan con:
12
+
13
+ - **Monorepos Melos** — múltiples paquetes y apps en un solo repo
14
+ - **Clean Architecture** — separación en capas `data`, `domain`, `presentation`
15
+ - **BLoC + Freezed** — manejo de estado con sealed classes
16
+ - **Atomic Design** — sistema de diseño con átomos, moléculas, organismos y templates
17
+ - **Widgetbook** — catálogo de componentes visuales
18
+ - **BFF (Backend For Frontend)** — integración con Retrofit + DI automática
19
+
20
+ En lugar de crear archivos a mano, wlmaker te hace las preguntas justas y genera todo el
21
+ scaffold con barrels, imports y registros de dependencias actualizados automáticamente.
22
+
23
+ ---
24
+
25
+ ## 2. Instalación y Primeros Pasos
26
+
27
+ ### Requisitos previos
28
+
29
+ | Requisito | Versión mínima |
30
+ |-----------|---------------|
31
+ | Node.js | 18+ |
32
+ | pnpm | Última estable |
33
+ | Flutter SDK | 3.x |
34
+ | Un monorepo Melos | root `pubspec.yaml` con `workspace:` / `melos:` (Melos 8) o legacy `melos.yaml` |
35
+
36
+ ### Instalación
37
+
38
+ ```bash
39
+ pnpm add -g wlmaker
40
+ ```
41
+
42
+ Verificá que funcione:
43
+
44
+ ```bash
45
+ wlmaker --version # → 1.7.0
46
+ wl --version # alias más corto
47
+ ```
48
+
49
+ ### Primer comando
50
+
51
+ Ejecutá `wlmaker` sin argumentos dentro de tu monorepo:
52
+
53
+ ```bash
54
+ cd tu-monorepo/
55
+ wlmaker
56
+ ```
57
+
58
+ Te va a recibir un menú interactivo con todas las opciones disponibles:
59
+
60
+ ```
61
+ ┌ wlmaker ┐
62
+ │ │
63
+ ◇ What do you want to create?
64
+ │ ● App
65
+ │ ○ BLoC
66
+ │ ○ Widget
67
+ │ ○ Widgetbook Use-Case
68
+ │ ○ Page
69
+ │ ○ Endpoint
70
+ │ ○ Package
71
+ │ ○ Env Var
72
+ │ ○ Personal Information
73
+ │ ○ Collaborative
74
+ │ ○ Docs
75
+ └ ┘
76
+ ```
77
+
78
+ ---
79
+
80
+ ## 3. Modos de Uso
81
+
82
+ wlmaker tiene **dos modos** de uso:
83
+
84
+ ### Modo interactivo
85
+
86
+ Ejecutás `wlmaker` sin argumentos (o `wlmaker <comando>` sin los argumentos requeridos) y
87
+ la CLI te guía paso a paso con preguntas, validación y selección de opciones.
88
+
89
+ **Ideal para:** cuando estás explorando, no recordás las opciones exactas, o preferís
90
+ que te lleve de la mano.
91
+
92
+ ### Modo directo
93
+
94
+ Pasás todos los argumentos en una sola línea. Útil para scripts, automatización, o cuando
95
+ ya sabés exactamente qué querés.
96
+
97
+ ```bash
98
+ wlmaker bloc user_login --no-build-runner
99
+ wlmaker widget toggle -t atom
100
+ wlmaker docs architecture
101
+ ```
102
+
103
+ **Ideal para:** CI/CD, scripts del Makefile, power users.
104
+
105
+ ---
106
+
107
+ ## 4. Guías Paso a Paso (Recetas)
108
+
109
+ Cada receta explica **cuándo usarla**, cómo ejecutarla en **modo directo** e **interactivo**,
110
+ y la estructura de archivos que vas a obtener.
111
+
112
+ ---
113
+
114
+ ### 4.1 Crear un BLoC
115
+
116
+ **Cuándo usarlo:** cuando necesitás manejar el estado de una pantalla o feature con
117
+ BLoC + Freezed (sealed classes).
118
+
119
+ #### Modo directo
120
+
121
+ ```bash
122
+ wlmaker bloc user_login
123
+ ```
124
+
125
+ Opciones disponibles:
126
+
127
+ | Opción | Descripción |
128
+ |--------|-------------|
129
+ | `-d, --dir <path>` | Directorio donde crear el BLoC (default: cwd) |
130
+ | `--no-build-runner` | No ejecutar `build_runner` después de generar |
131
+
132
+ #### Modo interactivo
133
+
134
+ ```bash
135
+ wlmaker bloc
136
+ # → Seleccioná el proyecto
137
+ # → Ingresá el nombre en snake_case
138
+ # → Confirmá si querés correr build_runner
139
+ ```
140
+
141
+ #### Resultado
142
+
143
+ ```
144
+ lib/features/<feature>/
145
+ ├── bloc.dart # ← actualizado: agrega export
146
+ └── user_login/
147
+ ├── user_login_bloc.dart # Bloc + Event + State (partes)
148
+ ├── user_login_event.dart # Evento sealed con Freezed
149
+ └── user_login_state.dart # Estado sealed con Freezed
150
+ ```
151
+
152
+ **Ejemplo:** `wlmaker bloc cart_checkout` genera `CartCheckoutBloc`, `CartCheckoutEvent`,
153
+ y `CartCheckoutState`.
154
+
155
+ ---
156
+
157
+ ### 4.2 Crear un Widget del Design System
158
+
159
+ **Cuándo usarlo:** cuando necesitás crear un componente visual siguiendo Atomic Design
160
+ (átomo, molécula, organismo, template).
161
+
162
+ #### Tiers disponibles
163
+
164
+ | Tier | Carpeta | Ejemplos |
165
+ |------|---------|---------|
166
+ | `atom` | `atoms/` | botón, input, ícono, texto |
167
+ | `molecule` | `molecules/` | search bar, card header |
168
+ | `organism` | `organisms/` | product card, checkout form |
169
+ | `template` | `templates/` | page layout, scaffold |
170
+
171
+ #### Modo directo
172
+
173
+ ```bash
174
+ wlmaker widget toggle -t atom
175
+ wlmaker widget search_bar -t molecule -p subdirectory-parts
176
+ wlmaker widget product_card -t organism -p subdirectory-show
177
+ ```
178
+
179
+ #### Modo desde JSON
180
+
181
+ También podés generar un widget completo desde un archivo JSON con el árbol de componentes:
182
+
183
+ ```bash
184
+ # Desde archivo
185
+ wlmaker widget --file docs/examples/molecule-product-card.json
186
+
187
+ # Desde JSON inline
188
+ wlmaker widget --json '{"componentName":"WlCard","tier":"molecule","mode":"component",...}'
189
+ ```
190
+
191
+ El JSON define propiedades, variantes, tokens, y el árbol completo de widgets (Container, Text, Icon, ComponentRef). Ver [`docs/JSON_SCHEMA.md`](docs/JSON_SCHEMA.md) para la documentación completa del formato.
192
+
193
+ **Modos disponibles:**
194
+ - `"mode": "component"` — genera el widget completo
195
+ - `"mode": "skeleton"` — genera solo el skeleton y lo vincula al componente existente (inyecta `part`, `isLoading`, y `if (isLoading) return WlXxxSkeleton()`)
196
+
197
+ **Widgetbook automático:** al generar un componente desde JSON, también se crea el use-case de Widgetbook con knobs interactivos para cada propiedad.
198
+
199
+ **Ejemplos:** ver `docs/examples/` con JSONs de prueba para atom, molecule, organism, template y skeleton.
200
+
201
+ #### Patrones por tier
202
+
203
+ | Tier | Patrones disponibles |
204
+ |------|---------------------|
205
+ | `atom` | `single-public` (default), `single-factory` |
206
+ | `molecule` | `single` (default), `subdirectory-parts`, `subdirectory-widgets` |
207
+ | `organism` | `subdirectory-show` (default), `single` |
208
+ | `template` | `simple` (default) |
209
+
210
+ #### Modo interactivo
211
+
212
+ ```bash
213
+ wlmaker widget
214
+ # → Ingresá el nombre
215
+ # → Seleccioná el tier
216
+ # → Elegí el patrón
217
+ ```
218
+
219
+ #### Resultado
220
+
221
+ Se genera el widget en `packages/design_system/lib/wl_design_system/<tier>/<widget>/`
222
+ y **automáticamente** se crea su use-case de Widgetbook.
223
+
224
+ ---
225
+
226
+ ### 4.3 Crear un Use-Case de Widgetbook
227
+
228
+ **Cuándo usarlo:** cuando ya tenés un widget y querés agregarle un showcase en Widgetbook
229
+ para que diseño/testers puedan verlo en aislamiento.
230
+
231
+ #### Modo directo
232
+
233
+ ```bash
234
+ wlmaker usecase toggle -t atom
235
+ ```
236
+
237
+ #### Opciones
238
+
239
+ | Opción | Descripción |
240
+ |--------|-------------|
241
+ | `-t, --tier` | Tier del widget (requerido) |
242
+ | `-d, --dir` | Raíz del proyecto (default: cwd) |
243
+ | `--no-build-runner` | No ejecutar build_runner |
244
+
245
+ #### Resultado
246
+
247
+ Se genera el use-case en `apps/widgetbook/lib/usecases/<tier>/` y se actualiza el barrel
248
+ de Widgetbook automáticamente.
249
+
250
+ ---
251
+
252
+ ### 4.4 Crear una Página (GoRoute + View)
253
+
254
+ **Cuándo usarlo:** cuando necesitás crear una pantalla nueva con navegación tipo GoRouter.
255
+
256
+ #### Modo directo
257
+
258
+ ```bash
259
+ wlmaker page profile -p /ruta/a/pages/
260
+ ```
261
+
262
+ #### Opciones
263
+
264
+ | Opción | Descripción |
265
+ |--------|-------------|
266
+ | `-p, --path` | Ruta absoluta al directorio `pages/` del feature |
267
+
268
+ #### Modo interactivo
269
+
270
+ ```bash
271
+ wlmaker page
272
+ # → Ingresá el nombre (o dejalo vacío para elegir del menú)
273
+ # → Seleccioná o ingresá la ruta al directorio pages/
274
+ ```
275
+
276
+ #### Resultado
277
+
278
+ ```
279
+ lib/features/<feature>/presentation/pages/
280
+ ├── pages.dart # ← actualizado: agrega export
281
+ └── profile/
282
+ ├── profile_page.dart # GoRoute + page builder
283
+ └── profile_view.dart # Widget de la vista
284
+ ```
285
+
286
+ ---
287
+
288
+ ### 4.5 Crear un Endpoint BFF
289
+
290
+ **Cuándo usarlo:** cuando necesitás integrar un nuevo endpoint del Backend For Frontend
291
+ con toda la stack de Clean Architecture.
292
+
293
+ #### Modo interactivo (único disponible)
294
+
295
+ ```bash
296
+ wlmaker endpoint
297
+ ```
298
+
299
+ El flujo te va a preguntar:
300
+
301
+ 1. **Proyecto** — detecta automáticamente el paquete de feature
302
+ 2. **Método HTTP** — `GET`, `POST`, `PUT`, `DELETE`, `PATCH`
303
+ 3. **Path del endpoint** — ej. `/api/v1/users/{userId}`
304
+ 4. **Nombre del caso de uso** — en snake_case, ej. `get_user_profile`
305
+ 5. **Archivo BFF API** — lo detecta automáticamente por dominio
306
+ 6. **Target de DI** — `app_base`, `app_base_loyalty`, o `none`
307
+ 7. **@lazySingleton** — si las dependencias se registran como lazy
308
+
309
+ #### Resultado
310
+
311
+ ```
312
+ lib/
313
+ ├── data/
314
+ │ ├── datasources/
315
+ │ │ └── <domain>_rest_datasource.dart # ← método inyectado
316
+ │ ├── models/
317
+ │ │ └── <feature>/
318
+ │ │ ├── <feature>.dart # ← barrel actualizado
319
+ │ │ ├── get_user_profile_model.dart
320
+ │ │ └── get_user_profile_request_model.dart # (si es POST/PUT/PATCH)
321
+ │ └── repositories/
322
+ │ └── <domain>_repository_data.dart # ← implementación inyectada
323
+ ├── domain/
324
+ │ ├── entities/
325
+ │ │ └── <feature>/
326
+ │ │ ├── <feature>.dart # ← barrel actualizado
327
+ │ │ └── get_user_profile_entity.dart
328
+ │ ├── repositories/
329
+ │ │ └── <domain>_repository.dart # ← interfaz inyectada
330
+ │ └── usecases/
331
+ │ └── <feature>/
332
+ │ ├── <feature>.dart # ← barrel actualizado
333
+ │ └── get_user_profile_usecase.dart
334
+ ```
335
+
336
+ Además, si elegiste un target de DI, se registran los módulos automáticamente:
337
+ - `DataSourceModule` ← datasource
338
+ - `RepositoriesModule` ← repository impl
339
+ - `UseCasesModule` ← use case
340
+
341
+ ---
342
+
343
+ ### 4.6 Crear un Paquete
344
+
345
+ **Cuándo usarlo:** cuando necesitás crear un paquete nuevo dentro del monorepo Melos.
346
+
347
+ #### Modo interactivo
348
+
349
+ ```bash
350
+ wlmaker package
351
+ ```
352
+
353
+ #### Resultado
354
+
355
+ ```
356
+ packages/<nombre>/
357
+ ├── lib/
358
+ │ ├── <nombre>.dart # barrel principal
359
+ │ └── src/
360
+ │ └── <nombre>.dart # implementación base
361
+ ├── test/
362
+ ├── pubspec.yaml # configurado con referencias del workspace
363
+ ├── analysis_options.yaml
364
+ ├── Makefile
365
+ └── .gitignore
366
+ ```
367
+
368
+ Además se actualizan:
369
+ - `.vscode/<monorepo>.code-workspace` — agrega la referencia al paquete
370
+ - `.helix/config` — si existe
371
+
372
+ ---
373
+
374
+ ### 4.7 Agregar Variable de Entorno
375
+
376
+ **Cuándo usarlo:** cuando necesitás agregar una variable de entorno (API key, URL, flag)
377
+ a través de toda la stack del monorepo.
378
+
379
+ #### Modo interactivo
380
+
381
+ ```bash
382
+ wlmaker env-var
383
+ ```
384
+
385
+ #### Resultado
386
+
387
+ La variable se inyecta en **6 capas**:
388
+
389
+ 1. Archivos JSON de entorno por app (dev, qa, prod)
390
+ 2. `AppEnvironment` — getter abstracto
391
+ 3. `AppBuildEnvironment` — implementación concreta
392
+ 4. `VendorsModule` — defaults de RemoteConfig
393
+ 5. `AppConfig` — entidad
394
+ 6. `AppConfigModel` — modelo
395
+
396
+ ---
397
+
398
+ ### 4.8 Crear una App
399
+
400
+ **Cuándo usarlo:** cuando necesitás crear una nueva aplicación Flutter en el monorepo
401
+ (ej. app de Colombia, app de Chile, etc.).
402
+
403
+ #### Modo interactivo
404
+
405
+ ```bash
406
+ wlmaker app
407
+ ```
408
+
409
+ El flujo te permite:
410
+ - Crear un **App Type** (tipo de mercado con locale, países soportados: CO, AR, CL, PE, EC, UY, BR, US)
411
+ - Crear una **App** completa con:
412
+ - `pubspec.yaml` configurado
413
+ - `flavorizr` (flavors: dev, qa, prod)
414
+ - Assets (PNGs, Lottie JSONs)
415
+ - Tema del design system
416
+ - Configs de Android (Kotlin + Gradle)
417
+ - Entitlements de iOS
418
+ - Registro en Widgetbook
419
+ - GitHub Actions workflows
420
+
421
+ ---
422
+
423
+ ### 4.9 Crear un Feature Colaborativo
424
+
425
+ **Cuándo usarlo:** cuando necesitás crear una feature completa que sigue el patrón
426
+ colaborativo del equipo (estructura predefinida con Clean Architecture, DI, barrels).
427
+
428
+ #### Modo directo
429
+
430
+ ```bash
431
+ wlmaker collaborative feature feature_orders
432
+ ```
433
+
434
+ #### Modo interactivo
435
+
436
+ ```bash
437
+ wlmaker collaborative
438
+ # → Elegí "feature"
439
+ # → Ingresá el nombre en snake_case
440
+ ```
441
+
442
+ #### Resultado
443
+
444
+ ```
445
+ packages/collaborative/<feature>/
446
+ ├── lib/
447
+ │ ├── data/
448
+ │ │ ├── api/bff/
449
+ │ │ ├── datasources/
450
+ │ │ ├── models/
451
+ │ │ └── repositories/
452
+ │ ├── domain/
453
+ │ │ ├── entities/
454
+ │ │ ├── repositories/
455
+ │ │ └── usecases/
456
+ │ ├── presentation/
457
+ │ │ ├── bloc/
458
+ │ │ └── pages/
459
+ │ └── di/ # Módulos de inyección
460
+ ├── pubspec.yaml
461
+ └── .gitignore
462
+ ```
463
+
464
+ ---
465
+
466
+ ### 4.10 Agregar Página a Feature Colaborativo
467
+
468
+ ```bash
469
+ wlmaker collaborative page order_detail -f packages/collaborative/feature_orders
470
+ ```
471
+
472
+ Agrega `order_detail_page.dart` + `order_detail_view.dart` y actualiza barrels.
473
+
474
+ ---
475
+
476
+ ### 4.11 Agregar BLoC a Feature Colaborativo
477
+
478
+ ```bash
479
+ wlmaker collaborative bloc order_form -f packages/collaborative/feature_orders
480
+ ```
481
+
482
+ Agrega `order_form_bloc.dart`, `order_form_event.dart`, `order_form_state.dart` y
483
+ actualiza el barrel del feature.
484
+
485
+ ---
486
+
487
+ ### 4.12 Agregar Endpoint a Feature Colaborativo
488
+
489
+ ```bash
490
+ wlmaker collaborative endpoint
491
+ # → Flujo interactivo guiado, similar a 4.5 pero dentro del feature colaborativo
492
+ ```
493
+
494
+ ---
495
+
496
+ ### 4.13 Scaffold de Personal Information (por país)
497
+
498
+ **Cuándo usarlo:** cuando necesitás crear el formulario de datos personales para un nuevo
499
+ mercado (país). Cada mercado puede tener distintos campos, validaciones, y modos de documento.
500
+
501
+ #### Modo interactivo (único disponible)
502
+
503
+ ```bash
504
+ wlmaker
505
+ # → Elegí "Personal Information"
506
+ ```
507
+
508
+ El flujo te pregunta:
509
+
510
+ | Paso | Qué define |
511
+ |------|-----------|
512
+ | AppType | Tipo de app/mercado (CO, AR, BR, etc.) |
513
+ | Market code | Código de 2 letras para la carpeta (ej. `co`, `ar`) |
514
+ | Market name | Nombre en PascalCase (ej. `Colombia`) |
515
+ | Campos | name, surname, email, document, gender, birthDate, issueDate, phone, loyaltyId |
516
+ | Modo documento | `selector` (tipo + número) o `custom` (input dedicado) |
517
+ | Formato fecha | `dd/MM/yyyy`, `MM/dd`, `MM/dd/yyyy`, `yyyy-MM-dd` |
518
+ | Phone preset | `default-full`, `brazil-full`, `local-only`, `custom` |
519
+ | Editabilidad | Campos editables después de guardar, bloqueados, siempre editables |
520
+ | Opciones booleanas | Skip email, account deletion, block fields, document card, info alert, info text, delete buttons por plataforma |
521
+
522
+ #### Resultado
523
+
524
+ ```
525
+ packages/personal_information/lib/countries/<code>/
526
+ ├── pi_config_<pais>.dart # Configuración específica del mercado
527
+ ├── pi_field_validation_<pais>.dart
528
+ ├── personal_information_form_<pais>.dart
529
+ ├── personal_information_body_<pais>.dart
530
+ ├── inputs/ # Widgets de input específicos
531
+ ├── widgets/ # Widgets compuestos
532
+ └── barrels actualizados
533
+ ```
534
+
535
+ ---
536
+
537
+ ## 5. Herramientas de Documentación
538
+
539
+ ### 5.1 Servir Documentación (Docusaurus)
540
+
541
+ ```bash
542
+ wlmaker docs serve
543
+ ```
544
+
545
+ Busca el directorio `book/` en el monorepo, instala dependencias npm si es necesario,
546
+ y levanta el servidor de desarrollo de Docusaurus.
547
+
548
+ ```bash
549
+ wlmaker docs serve -d /ruta/al/monorepo
550
+ ```
551
+
552
+ ### 5.2 Listar Comandos del Proyecto
553
+
554
+ ```bash
555
+ wlmaker docs commands
556
+ ```
557
+
558
+ Escanea los `Makefile` (raíz y book) y los scripts Melos (`melos.yaml` legacy o `melos.scripts` en el `pubspec.yaml` raíz) para extraer todos los comandos
559
+ disponibles y los muestra agrupados por fuente:
560
+
561
+ ```
562
+ Found 24 command(s)
563
+
564
+ Makefile
565
+ ├── gen → dart run build_runner build --delete-conflicting-outputs
566
+ ├── format → dart format lib test
567
+ ├── test → flutter test
568
+ └── ...
569
+
570
+ Melos
571
+ ├── analyze → melos run analyze
572
+ ├── gen:all → melos run gen:all
573
+ └── ...
574
+ ```
575
+
576
+ ### 5.3 Ver Arquitectura del Monorepo
577
+
578
+ ```bash
579
+ wlmaker docs architecture
580
+ ```
581
+
582
+ Muestra un árbol del monorepo con apps, paquetes, sus dependencias clave, sistema de
583
+ diseño y documentación:
584
+
585
+ ```
586
+ dc-wl-groceries-app (/Users/...)
587
+
588
+ ├── apps/
589
+ │ ├── app_co
590
+ │ ├── app_ar
591
+ │ └── widgetbook
592
+
593
+ ├── packages/
594
+ │ ├── app_base [flutter_bloc, retrofit, go_router]
595
+ │ ├── core [freezed, json_serializable]
596
+ │ ├── design_system [flutter_bloc, widgetbook]
597
+ │ │ └── features/
598
+ │ │ ├── home [flutter_bloc, freezed]
599
+ │ │ ├── cart [flutter_bloc, freezed, injectable]
600
+ │ │ └── ...
601
+
602
+ ├── design_system (atoms, molecules, organisms, templates)
603
+ ├── book/ (Docusaurus)
604
+ └── pubspec.yaml (workspace: + melos: — Melos 8) / melos.yaml (legacy)
605
+ ```
606
+
607
+ ---
608
+
609
+ ## 6. Consejos y Mejores Prácticas
610
+
611
+ ### Dónde ejecutar cada comando
612
+
613
+ | Comando | Dónde ejecutarlo |
614
+ |---------|-----------------|
615
+ | `bloc`, `widget`, `usecase`, `page` | En el paquete del feature (ej. `packages/features/cart/`) |
616
+ | `endpoint` | En el paquete del feature |
617
+ | `package`, `app`, `env-var` | Raíz del monorepo (donde está el `pubspec` con `workspace:` / `melos.yaml`) |
618
+ | `collaborative` | Raíz del monorepo |
619
+ | `personal-information` | Raíz del monorepo (necesita `packages/personal_information/`) |
620
+ | `docs` | Raíz del monorepo |
621
+
622
+ ### Barrels automáticos
623
+
624
+ **No edites los barrels a mano.** wlmaker actualiza automáticamente:
625
+ - `bloc.dart` en features
626
+ - Barriles de tier del design system
627
+ - `datasources.dart`, `entities.dart`, `models.dart`, `usecases.dart`
628
+ - Barriles internos de cada dominio
629
+
630
+ Si ves una exportación duplicada, wlmaker la detecta y la omite.
631
+
632
+ ### Cuándo usar `--no-build-runner`
633
+
634
+ Usá `--no-build-runner` cuando:
635
+ - Estás generando varios BLoCs/widgets en lote y querés correr `build_runner` una sola vez al final
636
+ - Ya sabés que build_runner va a fallar (ej. faltan dependencias)
637
+ - Estás en CI y build_runner se ejecuta en otro paso
638
+
639
+ ### Resolución automática de proyectos
640
+
641
+ Cuando ejecutás un comando que necesita un proyecto Flutter, wlmaker busca en este orden:
642
+
643
+ 1. **Directorio actual** — ¿tiene `pubspec.yaml` con `freezed` o `flutter_bloc`?
644
+ 2. **Monorepo Melos** — ¿estamos dentro de un monorepo? Escanea `packages/` y `packages/features/`
645
+ 3. **~/Development** — busca proyectos Flutter hasta 2 niveles de profundidad
646
+
647
+ Si hay múltiples proyectos, te muestra un selector interactivo.
648
+
649
+ ---
650
+
651
+ ## 7. Preguntas Frecuentes
652
+
653
+ ### "No encuentra mi proyecto"
654
+
655
+ wlmaker busca `pubspec.yaml` que contenga `freezed` o `flutter_bloc` en sus dependencias.
656
+
657
+ **Solución:** asegurate de que tu `pubspec.yaml` tenga al menos uno de estos paquetes.
658
+
659
+ ### "Not inside a monorepo"
660
+
661
+ Varios comandos (`package`, `app`, `collaborative`, `personal-information`, `docs`)
662
+ requieren estar dentro de un monorepo Melos.
663
+
664
+ **Solución:** ejecutalos desde la raíz del monorepo (donde el `pubspec.yaml` tiene
665
+ `workspace:` / `melos:`, o existe un `melos.yaml` legacy) o desde cualquier
666
+ subdirectorio — wlmaker busca hacia arriba.
667
+
668
+ ### "El build_runner falla"
669
+
670
+ Si `dart run build_runner build` falla después de generar un BLoC, puede ser por:
671
+ - Dependencias faltantes en el `pubspec.yaml`
672
+ - Código Dart con errores de sintaxis
673
+ - Conflicto con archivos generados anteriores
674
+
675
+ **Soluciones:**
676
+ 1. Usá `--no-build-runner` y corré build_runner manualmente después
677
+ 2. Ejecutá `dart run build_runner clean` antes de reintentar
678
+ 3. Revisá que `build_runner`, `freezed`, y `json_serializable` estén en `dev_dependencies`
679
+
680
+ ### "packages/personal_information not found"
681
+
682
+ El comando de Personal Information necesita que exista el paquete `packages/personal_information`
683
+ en tu monorepo.
684
+
685
+ **Solución:** primero creá el paquete base con `wlmaker package` o asegurate de que el
686
+ paquete exista en el monorepo.
687
+
688
+ ### "No AppTypes found"
689
+
690
+ El scaffold de Personal Information requiere al menos un AppType definido en
691
+ `packages/localization/lib/enum/app_type.dart`.
692
+
693
+ **Solución:** ejecutá `wlmaker app` primero y creá un App Type.
694
+
695
+ ---
696
+
697
+ ## 8. Referencia Rápida de Comandos
698
+
699
+ ### Comandos principales
700
+
701
+ | Comando | Argumento | Opciones principales | Descripción |
702
+ |---------|-----------|---------------------|-------------|
703
+ | `wlmaker` | — | — | Modo interactivo (menú) |
704
+ | `wlmaker bloc` | `[name]` | `-d`, `--no-build-runner` | Crear BLoC con Freezed |
705
+ | `wlmaker widget` | `<name>` | `-t` (tier), `-p` (pattern), `-j` (json), `-f` (file) | Crear widget del design system |
706
+ | `wlmaker usecase` | `<name>` | `-t` (tier), `--no-build-runner` | Crear use-case de Widgetbook |
707
+ | `wlmaker page` | `[name]` | `-p` (pages path) | Crear página GoRoute + View |
708
+ | `wlmaker endpoint` | — | — | Stack completa de endpoint BFF |
709
+ | `wlmaker package` | — | — | Crear paquete en el monorepo |
710
+ | `wlmaker env-var` | — | — | Agregar variable de entorno |
711
+ | `wlmaker app` | — | — | Crear y gestionar apps |
712
+
713
+ ### Comandos colaborativos
714
+
715
+ | Comando | Argumento | Opciones | Descripción |
716
+ |---------|-----------|----------|-------------|
717
+ | `wlmaker collaborative` | — | — | Menú interactivo colaborativo |
718
+ | `wlmaker collaborative feature` | `[name]` | — | Crear feature colaborativa completa |
719
+ | `wlmaker collaborative page` | `[name]` | `-f` (feature path) | Agregar página a feature |
720
+ | `wlmaker collaborative bloc` | `[name]` | `-f` (feature path) | Agregar BLoC a feature |
721
+ | `wlmaker collaborative endpoint` | — | — | Agregar endpoint a feature |
722
+
723
+ ### Comandos de documentación
724
+
725
+ | Comando | Opciones | Descripción |
726
+ |---------|----------|-------------|
727
+ | `wlmaker docs serve` | `-d` (project root) | Servir Docusaurus |
728
+ | `wlmaker docs commands` | `-d` (project root) | Listar Makefile + Melos scripts |
729
+ | `wlmaker docs architecture` | `-d` (project root) | Mostrar árbol del monorepo |
730
+
731
+ ### Flags comunes
732
+
733
+ | Flag | Aplica a | Descripción |
734
+ |------|----------|-------------|
735
+ | `-d, --dir <path>` | `bloc`, `widget`, `usecase` | Directorio del proyecto |
736
+ | `--no-build-runner` | `bloc`, `usecase` | No ejecutar build_runner |
737
+ | `-t, --tier <tier>` | `widget`, `usecase` | Tier: atom, molecule, organism, template |
738
+ | `-p, --pattern <pattern>` | `widget` | Patrón del widget |
739
+ | `-p, --path <path>` | `page` | Ruta al directorio pages/ |
740
+ | `-f, --feature <path>` | `collaborative page`, `collaborative bloc` | Ruta al paquete del feature |
741
+ | `-j, --json <json>` | `widget` | JSON string con el árbol del componente |
742
+ | `-f, --file <path>` | `widget` | Ruta a archivo JSON con el árbol del componente |
743
+
744
+ ---
745
+
746
+ ## ¡Eso es todo!
747
+
748
+ Si tenés dudas, revisá el [README](../README.md) o abrí un issue en
749
+ [github.com/MatiasZL/wlmaker-cli](https://github.com/MatiasZL/wlmaker-cli).