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

```bash
test -d "/home/lucas/fn_registry/apps/<name>" \
 || ls /home/lucas/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:
   ```bash
   ls /home/lucas/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):
    ```yaml
    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:

```bash
cd /home/lucas/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

```bash
# Buscar apps/<name>/ o projects/*/apps/<name>/
sqlite3 /home/lucas/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

```bash
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)

```bash
# Siempre
cd /home/lucas/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