---
name: init_api_app
kind: pipeline
lang: bash
domain: pipelines
version: "1.0.0"
purity: impure
signature: "init_api_app(nombre: string, [--port N], [--with-auth], [--with-db], [--with-ops]) -> void"
description: "Scaffold de Go HTTP API app en apps/{nombre}/. Genera main.go, handlers.go, config.go, migrations, Makefile, .env.example, .gitignore y app.md con frontmatter correcto. Compone funciones del registry (http_serve, http_router, http_middleware_chain, migration_up) y verifica con go vet."
tags: [init, scaffold, api, http, pipeline, bash, launcher]
uses_functions:
  - assert_command_exists_bash_shell
  - http_serve_go_infra
  - http_router_go_infra
  - http_middleware_chain_go_infra
  - http_logger_middleware_go_infra
  - http_cors_middleware_go_infra
  - http_json_response_go_infra
  - http_error_response_go_infra
  - migration_up_go_infra
  - jwt_generate_go_infra
  - password_hash_go_infra
  - password_verify_go_infra
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: nombre
    desc: "nombre de la app a crear (se usa como dir y binario en apps/{nombre}/)"
  - name: "--port"
    desc: "puerto por defecto del servidor HTTP (opcional, default 8080)"
  - name: "--with-auth"
    desc: "anade jwt_middleware, handlers login/register, tabla users en migration"
  - name: "--with-db"
    desc: "anade store.go con helpers CRUD y setup de SQLite al arrancar"
  - name: "--with-ops"
    desc: "anade fn ops init para crear operations.db con schema completo"
output: "estructura apps/{nombre}/ lista para ejecutarse con `make run`; si go vet falla, reporta error antes de declarar exito."
tested: false
tests: []
test_file_path: ""
example: "fn run init_api_app my_service --with-db"
file_path: "bash/functions/pipelines/init_api_app.sh"
---

## Sinopsis

```bash
fn run init_api_app <nombre> [--port N] [--with-auth] [--with-db] [--with-ops]
```

## Ejemplo rapido

```bash
fn run init_api_app billing_api --port 8090 --with-auth --with-db
cd apps/billing_api
cp .env.example .env
make run
# → starting billing_api on :8090
curl localhost:8090/health  # {"status":"ok"}
```

## Archivos generados

| Archivo | Descripcion |
|---------|-------------|
| `main.go` | Entry point con HTTPServe, router, middleware chain, graceful shutdown |
| `handlers.go` | Handlers de ejemplo (`/health`, `/api/v1/status`) con HTTPJSONResponse |
| `config.go` | Struct Config leida desde env vars con defaults |
| `migrations/001_initial.sql` | Schema inicial con tabla `items` (id, name, timestamps) |
| `Makefile` | Targets `build`, `run`, `dev`, `test`, `vet`, `clean` |
| `.env.example` | Variables PORT, DB_PATH, CORS_ORIGINS (+ JWT_SECRET con auth) |
| `.gitignore` | Binario, *.db, .env, IDE files |
| `go.mod` | Modulo Go con replace directive a fn-registry |
| `app.md` | Frontmatter con tag `service`, uses_functions reales, dir_path |

Con `--with-auth` anade ademas:
- `auth.go` — handlers `/auth/login`, `/auth/register` usando JWTGenerate, PasswordHash, PasswordVerify
- `migrations/002_users.sql` — tablas `users` y `sessions`

Con `--with-db` anade:
- `store.go` — struct Store con `NewStore`, `Ping` para acceso a SQLite

## Flags

| Flag | Efecto |
|------|--------|
| `--port N` | Puerto por defecto en config y .env.example (default: 8080) |
| `--with-auth` | Auth con JWT + bcrypt + tabla users |
| `--with-db` | Store con helpers CRUD + setup SQLite |
| `--with-ops` | fn ops init para operations.db |

## Post-setup

```bash
cd apps/{nombre}
cp .env.example .env
make run       # Arranca el server
make dev       # Hot via go run
make test      # Tests con fts5
```

## Notas

Pipeline impuro: escribe archivos al disco, ejecuta `go mod tidy` y `go vet`.

Compone heredocs para generar los archivos. Cada heredoc es reemplazable si alguna funcion del registry cambia de firma — ajustar el heredoc correspondiente.

Abort si `apps/{nombre}` ya existe para no sobrescribir.

El tag `launcher` permite que aparezca en el Pipeline Launcher TUI.