feat(ml): grupo comfyui-styles — catálogo curado + merge/dedup + generador LLM de estilos WAS

Tres funciones para gestionar y ampliar el repositorio de estilos del selector
WAS de ComfyUI (Prompt Styles Selector / Prompt Multiple Styles Selector):

- comfyui_curated_styles_catalog (pure): catálogo curado de 190 estilos en 13
  categorías (photography, render3d, painting, anime, pixel, illustration,
  comic, lighting, camera, material, scifi, fantasy, mood), formato WAS exacto.
- comfyui_append_styles (impure): merge+dedup no destructivo sobre el styles.json
  real, con backup atómico, validación de entradas y preservación de existentes.
- comfyui_generate_styles_llm (impure): genera estilos de una categoría vía
  ask_llm (grupo claude-direct); robusta (devuelve {} ante 429/JSON corrupto).

Aplicado en vivo: styles.json 269 -> 503 estilos (+190 curados +44 LLM),
backup hecho, selector verifica 503 en /object_info. Tests offline verdes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

python/functions/ml/comfyui_append_styles.md

@@ -0,0 +1,79 @@
+---
+name: comfyui_append_styles
+kind: function
+lang: py
+domain: ml
+version: "1.0.0"
+purity: impure
+signature: "def comfyui_append_styles(new_styles: dict, styles_path: str = DEFAULT_STYLES_PATH, overwrite: bool = False, backup: bool = True, dry_run: bool = False) -> dict"
+description: "Fusiona (merge+dedup) un dict de estilos nuevos sobre el styles.json del selector WAS de ComfyUI (Prompt Styles Selector / Prompt Multiple Styles Selector) de forma SEGURA y NO destructiva. Preserva TODOS los estilos existentes (dedup por nombre; los existentes ganan salvo overwrite=True), hace backup con timestamp antes de escribir, valida cada entrada nueva (descarta las que no tengan prompt no vacio, rellena negative_prompt por defecto si falta) y escribe de forma atomica (.tmp + os.replace). Devuelve un resumen con conteos antes/despues, anadidos, duplicados saltados e invalidos para verificar el efecto sin releer el archivo. Impura: lee y escribe disco; no usa red, no borra el original."
+tags: [comfyui, ml, comfyui-styles, styles, was, merge, dedup]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: error_go_core
+imports: []
+params:
+  - name: new_styles
+    desc: "dict {nombre: {'prompt': str, 'negative_prompt': str}} de estilos a anadir. Entradas sin prompt no vacio se descartan; las que no traen negative_prompt reciben uno por defecto. Debe ser un dict (si no, ValueError)."
+  - name: styles_path
+    desc: "Ruta del styles.json. Default: ~/ComfyUI/custom_nodes/was-node-suite-comfyui/styles.json (la instalacion WAS del usuario). Debe existir (no se crea de cero: FileNotFoundError)."
+  - name: overwrite
+    desc: "Si False (default), un nombre que ya existe NO se pisa (se cuenta como skipped_existing). Si True, los nuevos pisan a los existentes (overwritten)."
+  - name: backup
+    desc: "Si True (default), copia el archivo a <path>.bak.<epoch> antes de escribir. Backup hecho ANTES de tocar el original."
+  - name: dry_run
+    desc: "Si True, calcula el merge y los conteos pero NO escribe nada (ni backup). Para previsualizar el efecto."
+output: "dict resumen: {styles_path, backup_path, total_before, total_after, added:[nombres], overwritten:[nombres], skipped_existing:[nombres], invalid:[nombres], dry_run:bool}."
+tested: true
+tests: ["golden: merge preserva A y B existentes y anade C; total_before 2 -> total_after 3", "edge dedup: nombre existente no se pisa por defecto (skipped_existing), el original se conserva", "edge overwrite=True pisa el existente", "edge negative por defecto cuando la entrada nueva no lo trae", "edge entradas invalidas (no dict, prompt vacio, sin prompt) se descartan a invalid", "edge backup creado con el estado anterior", "error/edge dry_run no escribe el archivo (intacto) pero calcula conteos"]
+test_file_path: "python/functions/ml/comfyui_append_styles_test.py"
+file_path: "python/functions/ml/comfyui_append_styles.py"
+---
+
+## Ejemplo
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
+from ml.comfyui_append_styles import comfyui_append_styles
+from ml.comfyui_curated_styles_catalog import comfyui_curated_styles_catalog
+
+# Fusionar el catalogo curado sobre el styles.json real, preservando los existentes.
+nuevos = comfyui_curated_styles_catalog()           # 190 estilos curados
+res = comfyui_append_styles(nuevos)                  # backup + merge + dedup + escritura atomica
+print(res["total_before"], "->", res["total_after"], "anadidos:", len(res["added"]))
+# 269 -> 459 anadidos: 190  (los duplicados por nombre quedan en skipped_existing)
+
+# Previsualizar sin escribir:
+print(comfyui_append_styles(nuevos, dry_run=True)["total_after"])
+```
+
+O por CLI: `echo '{"x":{"prompt":"neon glow"}}' | python/.venv/bin/python3 python/functions/ml/comfyui_append_styles.py --dry-run`
+
+## Cuando usarla
+
+Cuando quieras AMPLIAR el repositorio de estilos del selector WAS de ComfyUI sin perder los que
+ya hay. Es el paso de escritura del flujo "generar estilos -> fusionar": genera un dict de estilos
+(con `comfyui_curated_styles_catalog` y/o `comfyui_generate_styles_llm`), pasalo aqui y el archivo
+queda fusionado con backup. Usala SIEMPRE en vez de editar el JSON a mano (preserva los existentes,
+valida formato, hace backup atomico). Tras escribir, reinicia `comfyui.service` para que el
+selector recargue el catalogo.
+
+## Gotchas
+
+- **Reinicio necesario**: el nodo WAS lee styles.json al arrancar. Despues de fusionar hay que
+  `systemctl --user restart comfyui.service` (o reiniciar el server) para que el selector liste
+  los nuevos. Verifica con `GET /object_info` contando los enum del `Prompt Styles Selector`.
+- **dedup por NOMBRE, no por contenido**: dos estilos con el mismo nombre se consideran el mismo;
+  por defecto gana el existente. Si quieres reemplazar deliberadamente, pasa `overwrite=True`.
+- **El archivo debe existir**: no se crea de cero (FileNotFoundError) para no enmascarar una
+  instalacion WAS rota. Si lo necesitas vacio, crea `{}` a mano primero.
+- **Backups se acumulan**: cada escritura deja un `styles.json.bak.<epoch>`. Limpialos a mano si
+  molestan; son la red de seguridad para restaurar.
+- **No versionar**: el styles.json es de ComfyUI, no de fn_registry. No hacer `git add` de el.
+
+## Capability growth log
+
+(v1.0.0 — sin cambios todavia.)