diff --git a/docs/init-pipelines.md b/docs/init-pipelines.md new file mode 100644 index 00000000..7c97b0fd --- /dev/null +++ b/docs/init-pipelines.md @@ -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 diff --git a/registry.db b/registry.db index 1c63f87f..b84bd831 100644 Binary files a/registry.db and b/registry.db differ