chore(issues): plan 0049 OSINT graph viewer multi-issue
Aggregates the planning artifacts for the 0049 series (umbrella + 0049a..0049k): - New rule cpp_apps.md (registered in INDEX) — standardize structure, CMake patterns, app.md frontmatter and sub-repo for C++ apps; points to the authoritative cpp/PATTERNS.md and cpp/DESIGN_SYSTEM.md. - Feature flag osint_graph_v1 (disabled until 0049k closes). - Issue 0049 (umbrella) and sub-issues 0049b..0049k describing the GPU rendering system, force-layout, types, sources, labels and the final graph_explorer app integration. - README updated with the new rows (all pending; 0049a will flip to completed in the next commit).
This commit is contained in:
@@ -22,3 +22,4 @@ Reglas operativas del proyecto. Cada archivo es una regla independiente.
|
||||
| 16 | [kiss.md](kiss.md) | KISS en proyectos y apps: cuestionar herramientas externas, sin abstracciones especulativas |
|
||||
| 17 | [apps_tbd.md](apps_tbd.md) | Trunk-based development obligatorio en apps generadas con `fn` (registry exento) |
|
||||
| 18 | [uses_functions.md](uses_functions.md) | Convencion de uses_functions para C++: el .md del consumidor declara las dependencias |
|
||||
| 19 | [cpp_apps.md](cpp_apps.md) | Estandarizacion de apps C++: estructura, CMake, app.md, sub-repo, runtime — apunta a cpp/PATTERNS.md y cpp/DESIGN_SYSTEM.md como autoritativas |
|
||||
|
||||
@@ -0,0 +1,148 @@
|
||||
## Estandarizacion de apps C++ del registry
|
||||
|
||||
**Fuentes autoritativas:**
|
||||
- `cpp/PATTERNS.md` — checklist y esqueleto del app shell (`fn::run_app`, AppConfig, panels, layouts, Settings, About).
|
||||
- `cpp/DESIGN_SYSTEM.md` — identidad visual (`fn_tokens`, ThemeMode, equivalencias `@fn_library` ↔ C++).
|
||||
|
||||
Esta regla NO duplica esos documentos — los señala como obligatorios y añade convenciones estructurales que no aparecen alli.
|
||||
|
||||
### 1. Ubicacion
|
||||
|
||||
| Caso | Donde vive |
|
||||
|---|---|
|
||||
| App independiente | `cpp/apps/<nombre>/` |
|
||||
| App de un proyecto | `projects/<proyecto>/apps/<nombre>/` |
|
||||
|
||||
NUNCA en `cpp/apps/<nombre>/` si pertenece a un proyecto, NUNCA fuera de `apps/` directamente. Ver `apps_location` en memoria + regla `apps_vs_functions.md`.
|
||||
|
||||
### 2. Estructura minima
|
||||
|
||||
```
|
||||
<app_dir>/
|
||||
CMakeLists.txt # usa add_imgui_app(target ...)
|
||||
app.md # frontmatter de registro (ver §4)
|
||||
main.cpp # entry: parseo de args + fn::run_app + render()
|
||||
[data.{h,cpp}] # opcional: capa de datos (DB / HTTP / archivos)
|
||||
[views.{h,cpp}] # opcional: composicion de paneles
|
||||
[<modulo>.{h,cpp}] # opcional: dominio especifico
|
||||
[vendor/] # opcional: deps no comunes (se prefieren las globales en cpp/vendor/)
|
||||
[.git/] # cada app es su propio repo Gitea (ver §6)
|
||||
```
|
||||
|
||||
**Reglas de split:**
|
||||
- `main.cpp` SIEMPRE — punto de entrada con `int main()` + `fn::run_app(...)` + funcion `render()`.
|
||||
- Si la app supera ~400 lineas en `main.cpp`, partir en `data.{h,cpp}` (carga/persistencia) + `views.{h,cpp}` (UI por panel).
|
||||
- Modulos especificos del dominio en archivos propios (`compiler.cpp` en `shaders_lab`, `data_http.cpp` en `registry_dashboard`).
|
||||
- NO crear archivos de "utilidades genericas" dentro de la app — eso va al registry como funcion (`cpp/functions/...`).
|
||||
|
||||
### 3. CMakeLists.txt
|
||||
|
||||
Patron canonico:
|
||||
|
||||
```cmake
|
||||
add_imgui_app(<target>
|
||||
main.cpp
|
||||
[extra_modules.cpp]
|
||||
# Funciones del registry usadas (paths absolutos):
|
||||
${CMAKE_SOURCE_DIR}/functions/<dominio>/<funcion>.cpp
|
||||
...
|
||||
)
|
||||
target_include_directories(<target> PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
|
||||
target_link_libraries(<target> PRIVATE [SQLite::SQLite3] [imgui_node_editor] ...)
|
||||
|
||||
if(WIN32)
|
||||
set_target_properties(<target> PROPERTIES WIN32_EXECUTABLE TRUE)
|
||||
endif()
|
||||
```
|
||||
|
||||
Reglas:
|
||||
- Usar SIEMPRE la macro `add_imgui_app(target ...)` — gestiona enlace con `fn_framework` y copia de TTFs.
|
||||
- Listar explicitamente cada `.cpp` del registry usado (no glob). Hace visible el grafo de dependencias.
|
||||
- NO listar `tokens.cpp`, `icon_font.cpp`, `app_settings.cpp`, `app_about.cpp`, `fps_overlay.cpp`, `panel_menu.cpp`, `app_menubar.cpp`, `layouts_menu.cpp`, `gl_loader.cpp`, `layout_storage.cpp` — viven en `fn_framework` y dan multiple-definition si se duplican.
|
||||
- En `WIN32`, marcar `WIN32_EXECUTABLE TRUE` para apps GUI (sin consola).
|
||||
|
||||
### 4. app.md (frontmatter)
|
||||
|
||||
Plantilla minima para apps C++:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <name>
|
||||
lang: cpp
|
||||
domain: <gfx|tui|tools|infra|...>
|
||||
description: "Frase corta — lo que hace y por que existe."
|
||||
tags: [imgui, ...] # si es service, anadir 'service'
|
||||
uses_functions: # IDs del registry — el indexer NO deduce C++
|
||||
- <nombre>_cpp_<dominio>
|
||||
- ...
|
||||
uses_types: []
|
||||
framework: "imgui"
|
||||
entry_point: "main.cpp"
|
||||
dir_path: "cpp/apps/<name>" o "projects/<proyecto>/apps/<name>"
|
||||
repo_url: "https://gitea-.../dataforge/<name>"
|
||||
---
|
||||
```
|
||||
|
||||
Reglas:
|
||||
- `uses_functions` se rellena a mano con los IDs de las funciones del registry usadas en `CMakeLists.txt`. Auditar con: `sqlite3 registry.db "SELECT id FROM apps WHERE id='<id>';"` + revisar diffs.
|
||||
- `framework: "imgui"` siempre que use `fn::run_app`. Otros valores solo si la app NO usa el shell (raro).
|
||||
- `tags`: incluir `service` si es daemon de larga duracion (ver `function_tags.md`).
|
||||
- `repo_url` apunta al sub-repo en Gitea (ver §6).
|
||||
|
||||
### 5. Registro en `cpp/CMakeLists.txt`
|
||||
|
||||
Cada app nueva se registra al final de `cpp/CMakeLists.txt`:
|
||||
|
||||
```cmake
|
||||
# --- <app_name> ---
|
||||
if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/apps/<name>/CMakeLists.txt)
|
||||
add_subdirectory(apps/<name>)
|
||||
endif()
|
||||
```
|
||||
|
||||
Para apps en proyectos (fuera del arbol `cpp/`):
|
||||
|
||||
```cmake
|
||||
# --- <app_name> (lives in projects/<proj>/apps/) ---
|
||||
set(_<NAME>_DIR ${CMAKE_SOURCE_DIR}/../projects/<proj>/apps/<name>)
|
||||
if(EXISTS ${_<NAME>_DIR}/CMakeLists.txt)
|
||||
add_subdirectory(${_<NAME>_DIR} ${CMAKE_BINARY_DIR}/apps/<name>)
|
||||
endif()
|
||||
```
|
||||
|
||||
El `if(EXISTS ...)` hace el registro tolerante a apps no clonadas (cada app es sub-repo separado).
|
||||
|
||||
### 6. Sub-repo Gitea (TBD obligatorio)
|
||||
|
||||
Cada app C++ es su propio repo en `dataforge/<name>` con branch `master`. Esto significa:
|
||||
- El directorio `<app_dir>/` esta en el `.gitignore` de `fn_registry` (excepto `app.md`).
|
||||
- El propio directorio tiene `.git/` apuntando al sub-repo.
|
||||
- TBD obligatorio mientras se desarrolla la app: ver `apps_tbd.md`. Trabajar en `issue/<NNNN>-<slug>` o `quick/<slug>`, mergear a `master` con `--no-ff`.
|
||||
- Sync entre PCs y push/pull se gestionan con `/full-git-push` y `/full-git-pull`.
|
||||
|
||||
### 7. Convenciones de runtime
|
||||
|
||||
Cumplir el checklist completo de `cpp/PATTERNS.md`. Resumen de lo que NUNCA debe aparecer en una app:
|
||||
|
||||
| Anti-patron | Sustituir por |
|
||||
|---|---|
|
||||
| `glfwInit()` en `main` | `fn::run_app(cfg, render)` |
|
||||
| `ImGui::StyleColorsDark()` | `cfg.theme = ThemeMode::FnDark` (default) |
|
||||
| `ImVec4(0.5,0.5,0.5,1)` | `fn_tokens::colors::*` |
|
||||
| `ImGui::Begin(u8"\xEF...")` | `ImGui::Begin(TI_HOME " ...")` |
|
||||
| Menubar inline cada frame | `cfg.panels` + `cfg.layouts_cb` |
|
||||
| About hardcoded en un panel | `cfg.about = {...}` |
|
||||
| `gl*` directo sin loader | `cfg.init_gl_loader = true` |
|
||||
| Tabla SQLite en la raiz del repo | `<app_dir>/<app>.db` (operations.db es solo para entities/relations/executions) |
|
||||
|
||||
### 8. Tests visuales (recomendado, no obligatorio)
|
||||
|
||||
Si la app tiene componentes que se quieren proteger contra regresiones visuales, anadir un demo en `cpp/apps/primitives_gallery/demos_<dominio>.cpp` que use los mismos componentes/funciones del registry. El sistema de capture-and-compare de `primitives_gallery --capture` funciona como golden-image gate (ver final de `cpp/PATTERNS.md`).
|
||||
|
||||
### 9. Decisiones que cada app debe tomar y documentar en su `app.md`
|
||||
|
||||
- `viewports`: `true` (default) si las ventanas pueden arrastrarse fuera del main; `false` si la app necesita estar siempre embebida.
|
||||
- `init_gl_loader`: `true` si llama `gl*` directo (renderers GPU custom como `graph_renderer`); `false` si solo usa ImGui/ImPlot.
|
||||
- `about` info: nombre, version (semver), descripcion 1 frase.
|
||||
- Persistencia: `<app>.db` SQLite junto al exe; nunca tocar `registry.db` ni `operations.db` salvo lectura.
|
||||
- Modo CLI: si la app acepta args, documentarlos en el `app.md` con ejemplos.
|
||||
Reference in New Issue
Block a user