fn_registry/docs/init-pipelines.md

Init Pipelines

Cuatro pipelines bash que scaffold apps completas en apps/ con un solo comando. Mismo patron que init_jupyter_analysis — componen funciones atomicas del registry para producir entornos listos para trabajar.

Todos son kind: pipeline, purity: impure, lang: bash, domain: pipelines. Llevan el tag launcher y aparecen en el Pipeline Launcher TUI.

Resumen

Pipeline	Para que	Flags
init_api_app	Go HTTP API service con graceful shutdown, middleware chain, migrations	--port N, --with-auth, --with-db, --with-ops
init_web_app	Full-stack: Go API + React frontend con Mantine y @fn_library	--port N, --with-auth, --with-db
init_desktop_app	Wails desktop app: Go backend + React frontend con Mantine	--with-db
init_cli_app	Go CLI con subcomandos, opcionalmente con TUI Bubbletea fullscreen	--with-tui

Arbol de decision

¿Que tipo de app necesitas?
│
├─ Un servicio HTTP/API
│   │
│   └─ ¿Necesitas frontend?
│       ├─ NO  → init_api_app
│       └─ SI  → init_web_app
│
├─ Una app de escritorio (ventana nativa)
│   │
│   └─ init_desktop_app
│
└─ Una herramienta de linea de comando
    │
    └─ ¿Quieres TUI interactiva?
        ├─ NO  → init_cli_app
        └─ SI  → init_cli_app --with-tui

Combinaciones comunes

API service con auth y DB

fn run init_api_app billing_api --port 8090 --with-auth --with-db
cd apps/billing_api
cp .env.example .env
make run
# → curl localhost:8090/health

Dashboard web full-stack

fn run init_web_app inventory_dashboard --with-auth
cd apps/inventory_dashboard
make install
# 2 terminales:
CGO_ENABLED=1 go run .                    # backend :8080
cd frontend && pnpm dev                    # frontend :5173 con proxy

Desktop app con SQLite

fn run init_desktop_app data_explorer --with-db
cd apps/data_explorer/frontend && pnpm install && cd ..
wails dev

CLI con TUI

fn run init_cli_app deploy_helper --with-tui
cd apps/deploy_helper
make build
./deploy_helper        # arranca TUI fullscreen
./deploy_helper status # subcomando CLI normal

Filosofia

1. Composicion sobre monolito: cada pipeline sourcea funciones atomicas del registry (assert_command_exists, etc.) — si una mejora, todos los pipelines se benefician.
2. Verificacion al final: cada pipeline termina con go vet, pnpm build o go mod tidy. Si falla, el pipeline reporta antes de declarar exito.
3. Defaults sensatos: el caso base (sin flags) genera una app funcional minima. Las flags anaden capas incrementales.
4. @fn_library como alias, no copia: los frontends generados referencian @fn_library via alias en vite.config.ts apuntando a frontend/functions/ui/ del registry.
5. app.md generado automaticamente: el frontmatter incluye uses_functions con los IDs reales que el boilerplate importa.
6. Abort si existe: si apps/{nombre}/ ya existe, el pipeline aborta sin sobrescribir.

Estructura generada por tipo

init_api_app

apps/{nombre}/
├── main.go              HTTPServe + router + middleware + graceful shutdown
├── handlers.go          healthHandler, statusHandler con HTTPJSONResponse
├── config.go            LoadConfig desde env vars
├── migrations/001_initial.sql
├── Makefile             build/run/dev/test/vet/clean
├── .env.example
├── .gitignore
├── go.mod               replace fn-registry → registry root
├── app.md
├── auth.go              (con --with-auth) login/register con JWT
├── migrations/002_users.sql  (con --with-auth)
└── store.go             (con --with-db) struct Store con Ping

init_web_app

Todo lo de init_api_app mas:

apps/{nombre}/
├── docker-compose.yml
└── frontend/
    ├── package.json     pnpm + vite + react + @mantine/core
    ├── vite.config.ts   alias @fn_library + proxy /api a backend
    ├── tsconfig.json
    ├── index.html
    ├── postcss.config.cjs
    └── src/
        ├── main.tsx     MantineProvider + App
        ├── App.tsx      AppShell con Burger + Navbar
        ├── theme.ts     createTheme()
        └── pages/Home.tsx  Consume /api/v1/status

init_desktop_app

apps/{nombre}/
├── main.go              Wails v2 con embed frontend/dist
├── app.go               struct App, bindings Greet, GetVersion
├── wails.json
├── go.mod               wails/v2 + replace fn-registry
├── app.md               framework: wails+vite+react+mantine
├── .gitignore
├── store.go             (con --with-db) Item + ListItems + CreateItem
└── frontend/            package.json, vite.config.ts, src/ con Mantine

init_cli_app

apps/{nombre}/
├── main.go              switch os.Args[1] — subcommand routing
├── cmd_version.go
├── cmd_status.go
├── Makefile             build/run (ARGS=...) /install/test/vet/clean
├── go.mod
├── app.md               framework vacio (CLI puro) o 'bubbletea' (TUI)
└── model.go             (con --with-tui) Modelo Bubbletea con list+spinner+dark theme

FAQ

¿Como anado auth despues?

Manualmente: anadir auth.go con los handlers, migrations/002_users.sql, y tag auth a app.md. Las funciones jwt_generate_go_infra, password_hash_go_infra, password_verify_go_infra estan en el registry.

Alternativa: regenerar con --with-auth en otro directorio y copiar manualmente los archivos relevantes.

¿Como cambio el puerto despues?

Editar config.go (cambiar default de Port) o pasar PORT=8090 via env var. El cliente HTTP del frontend (init_web_app) tiene el proxy en vite.config.ts — hay que ajustarlo alli tambien.

¿Como anado operations.db?

cd apps/{nombre}
FN_REGISTRY_ROOT=$(pwd)/../.. fn ops init .

Esto crea operations.db con schema completo. Para escribir entities/relations/executions usar fn ops entity add, etc.

¿Como agrego mas paginas al frontend?

Crear frontend/src/pages/Nueva.tsx y anadirla como ruta en App.tsx. Si quieres react-router, ya esta en el package.json de init_web_app.

¿Como desactivo las verificaciones al final del pipeline?

Las verificaciones de build del frontend (pnpm build) o Wails (wails build) se saltan con env vars:

SKIP_PNPM_BUILD=true fn run init_web_app my_app
SKIP_WAILS_BUILD=true fn run init_desktop_app my_app

go vet del backend no tiene opt-out — si falla, hay algo que corregir en los heredocs del pipeline.

¿Que pasa si fn-registry cambia el path?

Los pipelines embeben el path absoluto del registry en la directiva replace fn-registry => /abs/path del go.mod generado. Si el registry se mueve de directorio, hay que actualizar esa linea en cada app scaffoldeada.

¿Puedo scaffoldear en projects/{proyecto}/apps/ en vez de apps/?

De momento los 4 pipelines generan en apps/{nombre}/. Para un proyecto existe init_jupyter_analysis --project {proyecto} que crea en projects/{proyecto}/analysis/. Una mejora futura seria anadir --project a init_api_app/init_web_app/etc. Por ahora: generar en apps/ y mover manualmente (cuidado con los paths en replace y app.md).

Ver tambien

• init_jupyter_analysis_bash_pipelines — pipeline de referencia (scaffold analisis Jupyter)
• init_go_project_bash_pipelines / init_go_module_bash_pipelines — pipelines Go genericos (no apps)
• gitea_init_app_bash_pipelines — inicializar repo Gitea para una app scaffoldeada
• dev/issues/completed/0022-init-pipelines.md — spec original