---
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.)