fn_registry/.claude/commands/cpp-app.md

/cpp-app — Crear o modificar app C++ del registry sin olvidar nada

Recopila TODOS los datos necesarios (frontmatter, trio app_hub, panels, AppConfig, service block, e2e_checks, uses_functions) antes de tocar el disco. Tras confirmar, ejecuta scaffolder o edits, regenera iconos, refresca app_hub, compila y deploya a Windows.

Sustituye al flujo manual "edito main.cpp + app.md + CMakeLists.txt a mano". Wrapper sobre init_cpp_app_bash_pipelines (create) o edits directos sobre app.md (modify) + regenerate_app_icons + refresh_app_hub + redeploy_cpp_app_windows.

---

Uso

/cpp-app                       # interactivo, modo create
/cpp-app <name>                # interactivo, modo create con name pre-rellenado
/cpp-app modify <name>         # editar app existente

---

Modo CREATE — flujo turno a turno

Si $ARGUMENTS no empieza por modify, es create. Si trae <name>, lo usas como default; si no, pregunta name.

Paso 0 — verificar que no existe

test -d "$HOME/fn_registry/apps/<name>" \
 || ls $HOME/fn_registry/projects/*/apps/<name> 2>/dev/null

Si existe en cualquier ubicacion: abortar y sugerir /cpp-app modify <name>. NO sobreescribir.

Paso 1 — Identidad (AskUserQuestion)

1. name (texto libre — valida snake_case + contiene verbo segun ids_naming.md). Verbos canonicos: show, render, view, plot, edit, manage, monitor, browse, explore, run, launch, scan, audit, debug, profile, .... Si no trae verbo, sugerir alternativas (viewer -> <name>_viewer).
2. project (select: ninguno / lista de projects/*/). Si ninguno -> apps/<name>/.
3. domain (select: tools (default), gfx, tui, infra, finance, datascience, cybersecurity, shell, pipelines, browser).
4. description 1 linea (texto libre, max 80 chars). OBLIGATORIO — sin esto el hub muestra tarjeta vacia.

Paso 2 — Trio app_hub OBLIGATORIO

Regla dura cpp_apps.md: description + icon.phosphor + icon.accent SIEMPRE juntos.

5. icon.phosphor glyph name. Antes de preguntar, ofrece busqueda:

   ls $HOME/fn_registry/sources/phosphor-core/assets/fill/ | grep -i "<keyword>"
   

   Sugiere 3-5 candidatos basados en description. Default segun domain: gfx->palette, tui->terminal, tools->wrench, infra->gear, finance->chart-line-up, datascience->graph, cybersecurity->shield.
6. icon.accent hex #rrggbb (palette select):
   • sky #0ea5e9, indigo #4f46e5, violet #7c3aed, pink #ec4899, rose #f43f5e, red #dc2626, orange #ea580c, amber #d97706, green #16a34a, teal #0d9488, cyan #0891b2, slate #475569. Default segun domain.

Paso 3 — Tags

7. tags (multiSelect): service, launcher, dashboard, viewer, editor, monitor, debug, prototype. Si selecciona service -> activar bloque service (Paso 7).

Paso 4 — Panels iniciales

8. panels (texto libre o select):
   • Default: 1 panel Main (Ctrl+1).
   • Opcion lista: hasta 4 paneles. Por cada uno: {label, shortcut}. Generara PanelToggle k_panels[] en main.cpp.

Paso 5 — AppConfig flags

9. (multiSelect):
   • init_gl_loader (true si la app llama gl* directo, ej. shaders, GPU renderer custom). Default false.
   • viewports true (default) / false (single-window).
   • auto_dockspace true (default) / false (solo si gestiona DockSpace propio tipo shaders_lab).
   • fps_overlay activo de inicio? (controla solo el default; el menu Settings lo toggle).

Paso 6 — Funciones del registry a usar

10. uses_functions lista IDs. Antes de preguntar, busca candidatas segun description:

    mcp__registry__fn_search query="<keyword>" entity="functions"
    

    Y muestra capability groups relevantes (docs/capabilities/INDEX.md). El usuario puede aceptar lista, anadir IDs, o dejar vacio (se rellena tras codear).

    Cada ID que no este en el registry -> ofrecer spawn fn-constructor antes de continuar (regla delegation.md).

Paso 7 — Bloque service: (solo si tag=service)

11. Si paso 3 marco service, recopilar (regla function_tags.md + issue 0105):
    • port int o null
    • health_endpoint ruta GET o null
    • health_timeout_s (default 3)
    • runtime (select: systemd-user, systemd-system, docker-compose, stdio, manual)
    • systemd_unit (obligatorio si runtime empieza por systemd-)
    • systemd_scope (user|system|null)
    • restart_policy (select: always (Recommended — gotcha: on-failure NO reinicia SIGTERM limpio), on-failure, none)
    • pc_targets (multiSelect de pc_locations actuales: aurgi-pc, home-wsl, ...)
    • is_local_only (true/false default false)

Paso 8 — Persistencia

12. (multiSelect):
    • BD propia SQLite <name>.db en local_files/? -> recordar usar fn::local_path("<name>.db") (cpp_apps.md §7)
    • operations.db (para entities/relations)? -> ejecutar fn ops init tras crear
    • Archivos config en local_files/?

Paso 9 — e2e_checks (issue 0068)

13. Default sugerido (modificable):

    e2e_checks:
      - id: build
        cmd: "cmake --build cpp/build --target <name> -j"
        timeout_s: 300
      - id: self_test
        cmd: "./cpp/build/apps/<name>/<name> --self-test"
        timeout_s: 30
        severity: warning  # si todavia no implementa --self-test
    

    Pregunta: ¿anadir mas checks (ops_audit, pytest, smoke)?

Paso 10 — Resumen y confirmacion

Mostrar bloque YAML completo del app.md que se va a generar + flags del scaffolder + post-acciones. Pedir confirmacion antes de ejecutar.

---

Modo CREATE — ejecucion

Una vez confirmado:

cd $HOME/fn_registry

# 1. Scaffolder
./fn run init_cpp_app <name> \
  [--project <p>] \
  [--domain <d>] \
  --desc "<description>" \
  [--tags "<csv>"]

# 2. Editar app.md generado para anadir:
#    - icon: {phosphor, accent}
#    - service: {...}  (si aplica)
#    - uses_functions: [...]
#    - e2e_checks: [...]
#    (el scaffolder no rellena estos; editarlos con Edit tool)

# 3. Editar main.cpp generado para reflejar:
#    - panels[] custom (si != default)
#    - cfg.init_gl_loader / cfg.auto_dockspace / cfg.viewports
#    - includes de funciones registry usadas

# 4. Editar CMakeLists.txt para anadir paths de funciones del registry:
#    ${CMAKE_SOURCE_DIR}/functions/<d>/<f>.cpp

# 5. Si es service -> ofrecer crear systemd unit (skipear si runtime=stdio|manual)

# 6. Si pidio operations.db
./fn ops init apps/<name>  # o projects/<p>/apps/<name>

# 7. Generar icono
./fn run generate_app_icon "<phosphor>" "<accent>" "<dir>/appicon.ico"

# 8. Indexar
./fn index

# 9. Compilar Windows
./fn run redeploy_cpp_app_windows <name> <dir> --build

# 10. Refrescar app_hub
./fn run refresh_app_hub

# 11. Auditoria
./fn doctor cpp-apps
[[ "<tag>" == *service* ]] && ./fn doctor services-spec

---

Modo MODIFY — flujo

/cpp-app modify <name>

Paso 0 — Localizar

# Buscar apps/<name>/ o projects/*/apps/<name>/
sqlite3 $HOME/fn_registry/registry.db \
  "SELECT id, dir_path FROM apps WHERE name='<name>' AND lang='cpp';"

Si no existe: abortar, sugerir /cpp-app (sin args) para crear.

Paso 1 — Mostrar config actual

mcp__registry__fn_show id="<id>"
cat <dir>/app.md

Paso 2 — Que cambiar (multiSelect)

• description (1 linea)
• icon.phosphor o icon.accent
• tags (anadir/quitar; si toca service -> Paso 7 del create)
• uses_functions (anadir/quitar — recordar editar CMakeLists.txt)
• panels (anadir/quitar/renombrar)
• service: block (si tag=service)
• e2e_checks
• domain
• rename (cambia name, dir, IDs derivados, repo Gitea — operacion delicada, requiere doble confirmacion)

Paso 3 — Aplicar cambios

Para cada cambio: usa Edit sobre los archivos correspondientes. NUNCA Write completo de app.md (preserva campos que no toques).

Paso 4 — Post-acciones (segun lo que toco)

# Siempre
cd $HOME/fn_registry && ./fn index

# Si toco icon.* -> regenerar appicon
./fn run generate_app_icon "<phosphor>" "<accent>" "<dir>/appicon.ico"

# Si toco trio o panels o uses_functions o cambia code:
./fn run redeploy_cpp_app_windows <name> <dir> --build

# Si toco description o icon o tags:
./fn run refresh_app_hub

# Si toco service: o tag service
./fn doctor services-spec

# Siempre al final
./fn doctor cpp-apps

---

Reglas duras

• NUNCA crear main.cpp + CMakeLists.txt + app.md a mano. Siempre via init_cpp_app_bash_pipelines (regla cpp_apps.md).
• NUNCA poner el codigo en cpp/apps/<n>/. Solo apps/<n>/ o projects/<p>/apps/<n>/.
• NUNCA dejar app.md sin el trio (description + icon.phosphor + icon.accent). Tarjeta del hub queda gris.
• NUNCA declarar funciones del registry en uses_functions sin listar su .cpp en CMakeLists.txt (drift detectado por fn doctor uses-functions).
• NUNCA usar Restart=on-failure en systemd unit de un service C++ — gotcha 2026-05-17 (sqlite_api.service cayo 20h). Default Restart=always.
• Despues de cualquier cambio en el trio: regenerate_app_icons <name> + refresh_app_hub.

---

Auto-verificacion final

Tras crear o modificar, reportar al usuario:

=== app <name> ===
dir:           <abs_dir>
domain:        <d>
description:   "<desc>"
icon:          <phosphor> + <accent>
tags:          [<csv>]
uses_functions: N funciones (<list_top_5>)
panels:        N (<labels>)
e2e_checks:    N checks
service:       <si/no — port:<p> health:<h>>

Acciones ejecutadas:
  [✓] scaffolder / edits
  [✓] generate_app_icon
  [✓] fn index            (registry.db actualizado)
  [✓] redeploy_cpp_app_windows  (Desktop/apps/<name>/<name>.exe)
  [✓] refresh_app_hub     (tarjeta visible en hub)
  [✓] fn doctor cpp-apps  (limpio | N warnings)

Siguiente paso sugerido:
  - Abrir app_hub_launcher en Windows y verificar tarjeta
  - Anadir tests visuales si la app tiene paneles propios (cpp/PATTERNS.md §11)

$ARGUMENTS