fn_registry/.claude/commands/app.md

/app — Crear, configurar y desplegar apps del registry

Eres un agente orquestador de apps para fn_registry. Tu trabajo es crear apps completas que componen funciones del registry, configurar su entorno operativo, y publicarlas en Gitea. Usas los agentes especializados del ciclo reactivo para cada fase.

---

Argumento

$ARGUMENTS — nombre de la app y opcionalmente tipo/dominio/descripcion. Ejemplos:

/app crypto_dashboard
/app crypto_dashboard go finance "Dashboard TUI de criptomonedas"
/app mi_scraper py infra "Scraper de datos publicos"
/app deploy_helper bash infra "Helper de deployment"
/app wails:panel_ventas go finance "Panel de ventas con UI desktop"

Si no se proporciona nombre, preguntar al usuario que quiere construir.

El prefijo wails: indica que se debe usar scaffold_wails_app_go_infra para generar el proyecto con frontend integrado.

El prefijo service: indica que la app es un proceso de larga duracion (API, daemon, watcher). Añadir tag service automaticamente.

---

PASO 0: Entender que se va a construir

Antes de crear nada, recopilar contexto:

1. Parsear argumentos: nombre, lang (go|py|bash|ts), domain, descripcion
2. Si faltan datos, preguntar al usuario:
   • Que hace la app (descripcion)
   • En que lenguaje (default: go)
   • Que dominio (infra, finance, analytics, tools, etc.)
   • Si necesita UI (TUI con Bubbletea, desktop con Wails, o sin UI)
3. Consultar registry.db para encontrar funciones reutilizables:

# Buscar funciones relevantes por descripcion
sqlite3 $HOME/fn_registry/registry.db "SELECT id, kind, purity, lang, description FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'description:TERMINO* OR name:TERMINO*') ORDER BY name;"

# Buscar apps similares
sqlite3 $HOME/fn_registry/registry.db "SELECT id, name, lang, description, uses_functions FROM apps WHERE id IN (SELECT id FROM apps_fts WHERE apps_fts MATCH 'name:TERMINO* OR description:TERMINO*') ORDER BY name;"

# Verificar que el nombre no esta tomado
sqlite3 $HOME/fn_registry/registry.db "SELECT id FROM apps WHERE name = 'NOMBRE';"

4. Presentar plan al usuario antes de ejecutar:
   • Funciones del registry que se reutilizaran
   • Funciones nuevas que se necesitan crear
   • Estructura de la app
   • Confirmacion para proceder

---

PASO 1: CONSTRUIR — Crear funciones necesarias (@fn-constructor)

Si la app necesita funciones que no existen en el registry, invocar al agente fn-constructor para crearlas primero.

Cuando invocar fn-constructor:

• La app necesita logica pura que seria reutilizable (ej: un parser, un transformer, un validator)
• La app necesita un pipeline que compone funciones existentes
• La app necesita tipos nuevos para modelar su dominio

Como invocar:

Usar el Agent tool con subagent_type: "fn-constructor" pasando:

• Que funciones/tipos crear
• Que dominio y lenguaje
• Que funciones existentes reutilizar (IDs del registry)
• Contexto de para que se van a usar (la app que estamos creando)

NO invocar fn-constructor para:

• Logica especifica de la app que no es reutilizable (eso va directamente en la app)
• Codigo que depende de config/credenciales hardcodeadas

Despues de que fn-constructor termine, verificar que todo se indexo:

cd $HOME/fn_registry && ./fn index
# Verificar cada funcion creada
./fn show {id_de_cada_funcion}

---

PASO 2: Crear la app

Estructura base (todos los lenguajes)

mkdir -p $HOME/fn_registry/apps/{app_name}

app.md (OBLIGATORIO — siempre primero)

---
name: {app_name}
lang: {go|py|bash|ts|cpp}
domain: {domain}
description: "{descripcion}"
tags: [{tags}]  # Añadir "service" si es proceso de larga duracion
uses_functions:
  - {id_funcion_1}
  - {id_funcion_2}
uses_types: []
framework: "{bubbletea|wails|httpx|imgui|...}"
entry_point: "{main.go|main.py|main.sh}"
dir_path: "apps/{app_name}"
repo_url: ""
---

## Arquitectura

{Descripcion de como funciona la app, que funciones compone, flujo de datos}

## Notas

{Notas adicionales, dependencias externas, configuracion necesaria}

Si es un service (tag service), documentar ademas en el app.md:

• Puerto que usa (si expone HTTP/gRPC)
• Como lanzarlo y pararlo
• Health check (como comprobar que esta vivo)

.gitignore (OBLIGATORIO)

operations.db
operations.db-wal
operations.db-shm
__pycache__/
build/
*.exe
*.log

Segun lenguaje:

Go (CLI/TUI):

cd $HOME/fn_registry/apps/{app_name}
go mod init fn_registry/apps/{app_name}
# Crear main.go, app/, config/, views/ segun necesidad

Go (Wails — desktop con UI):

# Usar scaffold del registry
cd $HOME/fn_registry
./fn run scaffold_wails_app -- --name {app_name} --dir apps/{app_name}

Python:

# Crear main.py con sys.path al registry
# Import pattern: sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "python", "functions"))

Bash:

# Crear main.sh con source a funciones del registry
# Pattern: source "$REGISTRY_ROOT/bash/functions/{domain}/{func}.sh"
chmod +x $HOME/fn_registry/apps/{app_name}/main.sh

Inicializar operations.db

cd $HOME/fn_registry
FN_REGISTRY_ROOT=$HOME/fn_registry ./fn ops init apps/{app_name}

Indexar en registry.db

cd $HOME/fn_registry && ./fn index
# Verificar
sqlite3 registry.db "SELECT id, name, lang, domain FROM apps WHERE name = '{app_name}';"

---

PASO 3: EJECUTAR — Verificar que funciona (@fn-executor)

Invocar al agente fn-executor para:

1. Verificar que la app compila/ejecuta correctamente
2. Configurar entities y relations en operations.db si la app maneja datos
3. Ejecutar una primera ejecucion de prueba
4. Registrar la ejecucion con metricas

Como invocar:

Usar el Agent tool con subagent_type: "fn-executor" pasando:

• Nombre y directorio de la app (apps/{app_name})
• Lenguaje y entry point
• Que debe ejecutar y con que argumentos de prueba
• Si debe crear entities/relations (cuando la app transforma datos)

---

PASO 4: AUDITAR — Verificar integridad (@fn-recopilador)

Invocar al agente fn-recopilador para auditar que todo quedo bien:

1. Estructura de la app (app.md, operations.db, .gitignore)
2. Schema de operations.db completo
3. Integridad de datos (entities, relations, executions)
4. Coherencia con registry.db (uses_functions, type_refs)
5. App indexada correctamente

Como invocar:

Usar el Agent tool con subagent_type: "fn-recopilador" pasando:

• Nombre de la app a auditar
• Que es una app nueva y debe verificar todo desde cero

Si el recopilador detecta problemas, corregirlos antes de continuar.

---

PASO 5: PUBLICAR en Gitea (@gitea) — OBLIGATORIO

Toda app nueva DEBE publicarse en Gitea. Este paso NO es opcional.

Como invocar:

Usar el Agent tool con subagent_type: "gitea" pasando:

• Crear repo {app_name} en la organizacion dataforge de Gitea
• La URL base de Gitea: https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com
• Inicializar el repo con el contenido de apps/{app_name}/
• El repo debe tener su propio .git independiente del fn_registry

Pasos que el agente gitea debe ejecutar:

# 1. Crear repo en Gitea (via API)
# 2. Inicializar git en la app
cd $HOME/fn_registry/apps/{app_name}
git init
git add -A
git commit -m "Initial commit: {app_name} — {descripcion}"

# 3. Configurar remote y push
git remote add origin https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/dataforge/{app_name}.git
git push -u origin master

# 4. Actualizar repo_url en app.md

Despues de publicar, actualizar el repo_url en app.md y re-indexar:

cd $HOME/fn_registry && ./fn index

---

PASO 6: Resumen final

Reportar al usuario:

=== APP CREADA: {app_name} ===

Directorio:  apps/{app_name}/
Lenguaje:    {lang}
Dominio:     {domain}
Framework:   {framework}
Entry point: {entry_point}

Funciones del registry usadas:
  - {id1}: {descripcion}
  - {id2}: {descripcion}

Funciones nuevas creadas:
  - {id3}: {descripcion}

Operations:
  Entities:  N
  Relations: N
  Executions: N (primera ejecucion: {status})

Repo Gitea: {repo_url}

Para ejecutar:
  cd apps/{app_name} && {comando_ejecucion}

---

Flujos segun tipo de app

App Go TUI (Bubbletea)

1. Consultar funciones TUI existentes: sqlite3 registry.db "SELECT id, description FROM functions WHERE domain = 'tui' ORDER BY name;"
2. Crear app con framework bubbletea
3. Estructura: main.go + app/model.go + views/ + config/
4. Tag launcher en app.md si debe aparecer en Pipeline Launcher

App Go Desktop (Wails)

1. Usar scaffold_wails_app_go_infra para generar el proyecto
2. Consultar componentes Wails del registry: sqlite3 registry.db "SELECT id, description FROM functions WHERE id LIKE '%wails%' ORDER BY name;"
3. Frontend usa @fn_library (Mantine v9, @tabler/icons-react)
4. Bindings Go via wails_bind_crud_go_infra

App Python

1. Consultar funciones Python: sqlite3 registry.db "SELECT id, description FROM functions WHERE lang = 'py' AND domain = 'DOMINIO' ORDER BY name;"
2. Import pattern con sys.path al registry
3. Deps con requirements.txt o pyproject.toml

App Bash

1. Consultar funciones Bash: sqlite3 registry.db "SELECT id, description FROM functions WHERE lang = 'bash' ORDER BY name;"
2. Source pattern con REGISTRY_ROOT
3. set -euo pipefail obligatorio

App C++ (ImGui)

1. Codigo fuente va en apps/{app_name}/ (no en cpp/apps/)
2. cpp/CMakeLists.txt referencia la app con add_subdirectory(../apps/{app_name} ...)
3. Funciones C++ del registry se incluyen como .cpp en el CMakeLists.txt de la app
4. Para Windows: cross-compile con cmake -DCMAKE_TOOLCHAIN_FILE=toolchains/mingw-w64.cmake

Service (tag service)

1. Detectar si el usuario pide un servicio (API, daemon, watcher, server) o usa prefijo service:
2. Añadir tag service al array tags del app.md
3. Documentar en app.md: puerto, como lanzar/parar, health check
4. Estructura tipica para un HTTP service en Go:

   apps/{service_name}/
   ├── app.md           # tags: [service, api, ...]
   ├── main.go          # Bind port, listen, graceful shutdown
   ├── handlers.go      # HTTP handlers que componen funciones del registry
   ├── go.mod
   ├── .gitignore
   

5. El service se ejecuta como: go run . --port 8080
6. Para consultar services existentes: sqlite3 registry.db "SELECT id, name, description FROM apps WHERE tags LIKE '%service%';"

---

Reglas

• Codigo reutilizable va en functions/, NO en la app → usar fn-constructor
• Codigo especifico de la app va en apps/{app_name}/
• Todas las apps van en apps/, incluidas C++, TypeScript, etc. Nunca en cpp/apps/ ni otros subdirectorios
• operations.db SOLO dentro de la app, NUNCA en la raiz
• registry.db SOLO en la raiz, NUNCA en apps
• Toda app DEBE tener app.md con frontmatter completo
• uses_functions en app.md DEBE listar TODAS las funciones del registry importadas
• Siempre ./fn index despues de crear/modificar la app — verificar que aparece en registry.db
• Siempre auditar con fn-recopilador antes de publicar
• Siempre publicar en Gitea (PASO 5) — toda app tiene repo en dataforge/{app_name}
• Siempre actualizar repo_url en app.md despues de publicar y re-indexar
• Tag service: añadir a apps que son procesos de larga duracion (APIs, daemons, watchers, schedulers)
• Tag launcher: añadir a pipelines que deben aparecer en Pipeline Launcher TUI

$ARGUMENTS