# AGENTS.md — boogiepop-cli

Este es el CLI `boogiepop` para gestionar versiones de seeds en proyectos Boogiepop.

## Qué podés hacer con este repo

- Leer y entender los comandos disponibles
- Agregar nuevos comandos en `src/commands/`
- Modificar la lógica de update/merge en `src/commands/update.ts`

## Qué NO tocar sin autorización del Owner

- `.github/workflows/release.yml` — pipeline de distribución
- `package.json` campo `bin` y `pkg` — afecta cómo se distribuye el CLI

---

## Estructura

```
src/
  index.ts              — entry point, registra todos los comandos
  commands/
    version.ts          — bp version: versión actual del seed
    versions.ts         — bp versions: versiones disponibles en el template
    update.ts           — bp update: selector interactivo + aplica merge
    new.ts              — boogiepop new: wizard crear proyecto (Bootstrap MS)
    abort.ts            — bp abort: aborta merge activo o squash staged
    config.ts           — bp config: configura boogiepop.json
    docs.ts             — bp docs: servidor de docs local
  lib/
    bootstrap-client.ts — SSE + availability contra Bootstrap MS
    bootstrap-config.ts — ~/.boogiepop/bootstrap.json
  utils/
    smart-merge.ts      — lógica de merge preservando cambios locales
    validation.ts       — validación de proyecto Boogiepop
    prompt.ts           — helpers de inquirer
    preserve-config.ts  — preserva federation config durante merge
```

---

## Cómo usar el CLI (contexto para LLMs)

Si estás en un proyecto que tiene `boogiepop.json`, podés usar estos comandos:

```bash
boogiepop version          # ver versión actual del seed
boogiepop versions         # ver versiones disponibles con descripción
boogiepop update           # actualizar interactivamente
boogiepop abort            # abortar si algo salió mal
```

### Cuándo sugerir cada comando

| Situación | Comando recomendado |
|-----------|---------------------|
| El usuario pregunta en qué versión está | `boogiepop version` |
| El usuario pregunta si hay updates | `boogiepop versions` |
| El usuario quiere actualizar el seed | `boogiepop update` |
| Hay conflictos y el usuario quiere cancelar | `boogiepop abort` |
| El proyecto no tiene `boogiepop.json` | `boogiepop config -u <url-del-seed>` |

### boogiepop.json

Siempre verificar si existe antes de sugerir comandos. Si no existe, el primer paso es `boogiepop config -u <url>`.

```json
{
  "version": "1.0.1",
  "template": {
    "url": "https://github.com/blanck1945/boogiepop-react-seed",
    "remote": "template-origin",
    "branch": "main"
  }
}
```

### Después de `boogiepop update`

El update deja los cambios staged pero sin commitear. El usuario debe:
1. Revisar los cambios con `git diff --cached`
2. Hacer `git commit` para finalizar
3. O `boogiepop abort` para cancelar

---

## Crear app nueva — flujo AI-first (`boogiepop new`)

Boogiepop está pensado **IA first**: el usuario puede pedir en lenguaje natural (*“creá una app vite en boogiepop”*) y el agente ejecuta el mismo camino que un humano con el CLI.

**Regla de oro:** usar **solo** `boogiepop new` (sin scripts auxiliares, sin llamadas directas al Bootstrap MS, sin `register-app` manual, sin tocar el hub manifest). Si algo falla, reportar el error y preguntar antes de hacer limpieza o pasos extra.

Documentación técnica completa: [`docs/CLI-BOOTSTRAP-INFRA.md`](docs/CLI-BOOTSTRAP-INFRA.md). Almacenamiento S3 por app: [`docs/APP-STORAGE.md`](docs/APP-STORAGE.md).

### Prerrequisitos (verificar antes de crear)

1. `boogiepop` instalado (`boogiepop --version`)
2. Bootstrap MS configurado: `~/.boogiepop/bootstrap.json` (comando previo: `boogiepop bootstrap config --url <URL> --key <KEY>`)
3. Directorio de trabajo elegido (donde quedará `./<nombre>` al clonar). Por defecto: carpeta padre del monorepo o la que indique el usuario.

### Qué inferir del prompt del usuario

| Dato | Cómo inferirlo |
|------|----------------|
| **Tipo** | “vite”, “remote”, “module federation” → `vite`. “next”, “dashboard” → `next`. “streamlit” → `streamlit`. |
| **Nombre** | Solo si el usuario lo dice explícitamente. **No inventar** slug. |
| **Visibilidad** | Si no dice nada → **preguntar** (`public` / `private`). Default del wizard: `public`. |
| **Infra AWS** | Si no dice nada → **preguntar** (Terraform ECS + ALB + S3 + Secrets). Default del wizard: **sí**. |
| **Colaboradores** | Si no menciona → asumir **ninguno** (Enter vacío en el wizard). |
| **Clonar local** | Default: sí. Solo usar `--no-clone` si el usuario lo pide. |
| **Registro en plataforma** | Default: sí (al terminar, `hubVisible=false`). Solo `--skip-register` si el usuario lo pide. |

### Datos que **siempre** hay que tener antes de ejecutar

Si falta alguno, **preguntar al usuario** — no asumir ni reutilizar valores de conversaciones anteriores:

1. **Nombre del proyecto** (slug humano, ej. `stock-market`)
2. **Tipo** (`next` | `vite` | `streamlit`) — si el prompt no lo deja claro
3. **Visibilidad del repo** (`public` | `private`)
4. **¿Crear infra AWS?** (sí / no)
5. **Directorio** donde correr `boogiepop new` (si no es el cwd obvio)
6. (Opcional) Colaboradores GitHub + rol (`admin` | `write` | `read`)

Opcionalmente confirmar con `--dry-run` **solo si el usuario lo pide**; no es parte del flujo normal.

### Cómo ejecutar

**Humano (terminal):**

```bash
cd <directorio-elegido>
boogiepop new
```

**Agente / CI** (respuestas ya recopiladas del usuario):

```bash
cd <directorio-elegido>
boogiepop new -y \
  --name <nombre> \
  --type next|vite|streamlit \
  --visibility public|private
```

Con infra AWS (default): omitir flag. Sin infra: agregar `--no-provision-infra`.

Ejemplo:

```bash
boogiepop new -y --name stock-market --type vite --visibility private
```

`-y` requiere `--name` y `--type`. No abre el wizard; si el nombre no está disponible, falla con el listado de conflictos (no repregunta).

El agente debe:

1. Recopilar respuestas faltantes conversando con el usuario.
2. Mostrar un **resumen** (nombre, tipo, visibilidad, infra, colaboradores, directorio) y pedir OK explícito.
3. Lanzar `boogiepop new -y ...` con esos valores (o guiar al humano por el wizard si prefiere modo interactivo).
4. Ir reportando **updates** según la salida SSE: validación → Terraform → repo → clone → `npm install` → registro.

### Respuestas del wizard (orden real en `new.ts`)

| Pregunta del CLI | Respuesta acordada con el usuario |
|------------------|-----------------------------------|
| Nombre del proyecto | `<nombre>` |
| Tipo de template | Next.js / **Vite** / Streamlit |
| Visibilidad del repo | public / **private** |
| ¿Crear infra AWS? | Yes / No |
| Username colaborador | Enter vacío para terminar (o usernames + rol) |
| ¿Crear proyecto? | Yes |

Si el nombre no está disponible, el CLI **vuelve a pedir otro nombre** (muestra conflictos: repo GitHub, carpeta local, Terraform en EFS). El agente debe informar al usuario y pedir un nombre alternativo — no improvisar limpieza en AWS/EFS sin permiso.

### Qué hace el flujo al terminar bien

- Repo en GitHub (`Boogiepop-remotes` para vite/streamlit; org personal para next)
- Infra AWS (si eligió sí): ECR, ECS, ALB path, S3, Secrets
- Clone en `./<nombre>` + `npm install` (vite/next)
- Registro en plataforma (`hubVisible=false`, **sin** publish automático)
- **Verificación de deploy:** el Bootstrap MS espera GitHub Actions tras el push y comprueba la URL en producción; el CLI muestra un resumen final (✅ todo OK / ⚠ falló o pendiente)

### Qué **no** hacer el agente

- No llamar `POST /bootstrap/projects` ni otros endpoints a mano.
- No usar scripts `_tmp-*`, `_finish-*`, ni atajos fuera del CLI.
- No editar `hub-apps-manifest*.json` ni subir manifest a S3 salvo pedido explícito.
- No borrar infra/repos/EFS por cuenta propia si algo falló — **preguntar** primero.
- No commitear ni pushear salvo que el usuario lo pida.

### Si falla algo

Reportar en lenguaje claro:

- **En qué paso** (Terraform, repo, clone, npm, registro).
- **Mensaje de error** relevante.
- **Qué sí se creó** (ej. Terraform a medias sin repo).

Luego preguntar cómo seguir (reintentar otro nombre, limpieza, `--no-clone`, etc.).

### Referencia rápida de flags

| Flag | Uso |
|------|-----|
| `-y, --yes` | Sin wizard; requiere `--name` y `--type` (modo agente) |
| `--name <name>` | Nombre del proyecto |
| `-t, --type <type>` | `next` \| `vite` \| `streamlit` |
| `--visibility <v>` | `public` o `private` (default: `public`) |
| `--no-provision-infra` | No crear infra AWS antes del repo |
| `--dry-run` | Ver payload JSON sin crear nada |
| `--no-clone` | Crear repo/infra pero no clonar en cwd |
| `--skip-register` | No registrar app en plataforma al final |

### Cuándo sugerir `boogiepop new`

| Situación | Acción |
|-----------|--------|
| “Creá / nueva app / remote vite / micro-frontend” | Flujo AI-first arriba |
| “Registrá una app que ya existe en disco” | `boogiepop register-app` (otro comando) |
| “Publicá en el hub” | `boogiepop publish` (después de register) |
| Bootstrap no configurado | `boogiepop bootstrap config` primero |