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

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

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

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

### CLI con TUI

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

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

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