docs: guia consolidada docs/init-pipelines.md + regenerar registry.db
docs/init-pipelines.md: referencia rapida de los 4 init pipelines con tabla resumen, arbol de decision, combinaciones comunes, FAQ y estructura generada por tipo. registry.db: re-indexado para registrar los 4 nuevos pipelines como kind=pipeline, purity=impure, domain=pipelines, tag=launcher. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,199 @@
|
||||
# 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
|
||||
BIN
Binary file not shown.
Reference in New Issue
Block a user