kcreate-scaffolding-gcp-script 0.0.0-stage → 0.2.0

package/skill/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: kcreate-scaffolding-gcp-script
+description: Genera el scaffolding de Terragrunt (live/<entorno-nuevo>/) para un proyecto GCP nuevo, copiando y adaptando un entorno ya existente del mismo repo. Úsalo siempre que el usuario pida crear un nuevo entorno/proyecto de GCP a partir de uno existente, generar los scripts de Terragrunt para un ambiente nuevo, o "clonar" un entorno como boletera-qa/cashless-qa/xoloshop-qa hacia uno nuevo — incluso si no menciona la palabra "skill" o "scaffolding" explícitamente. NO despliega nada en GCP (eso es un paso posterior, manual).
+---
+
+# kcreate-scaffolding-gcp-script
+
+Genera `live/<NEW_ENV>/` completo copiando y adaptando `live/<SOURCE_ENV>/`
+en el mismo repo. Todo el trabajo pesado lo hacen scripts de shell
+determinísticos en `scripts/` — tu trabajo como agente es **orquestarlos
+en el orden correcto y reportar sus mensajes tal cual**, no editar HCL a
+mano ni decidir valores por tu cuenta.
+
+**Por qué scripts y no ediciones manuales:** cada sustitución manual de un
+nombre de entorno, un rango CIDR o una lista de APIs es una oportunidad de
+error que solo se descubre en el momento real de desplegar en GCP (ver
+`references/lessons-learned.md` — todos los casos documentados ahí ya
+rompieron un despliegue real alguna vez). Los scripts de este skill existen
+para que esos errores ya no puedan volver a pasar, no para ahorrar
+tipeo.
+
+## Requiere
+
+- `bash`, `python3` (stdlib `ipaddress`, sin paquetes externos), `git`,
+  `curl`, GNU `sed`.
+- El repo destino debe seguir la convención
+  `live/<entorno>/<componente>/terragrunt.hcl` + `Makefile` + `.gitignore`
+  (la misma de `club-tijuana/infra-cloud`).
+- `github-proyect-tracking` instalado junto a este skill (lo hace
+  `install.sh` de este mismo repo automáticamente — si no está, los
+  scripts lo detectan y terminan con un mensaje claro en vez de fallar a
+  medias).
+
+## Parámetros
+
+| Parámetro | Obligatorio | Descripción |
+|---|---|---|
+| `SOURCE_ENV` | sí | Entorno ya existente a copiar. Debe existir en `live/<SOURCE_ENV>/project/terragrunt.hcl` del repo destino. Cualquier entorno vale — no está fijo a uno en particular. |
+| `NEW_ENV` | sí | Id del entorno nuevo, patrón `<app>-<qa\|prod>` en minúsculas (ej. `xoloshop-prod`). De aquí se infiere `PROJECT_NAME` (ej. `Xoloshop-Prod`) — ver sección 3.4 de `references/lessons-learned.md` si la app tiene una capitalización no obvia. |
+
+Todo lo demás (repo de GitHub de la app, URL de tracking, org id,
+versiones, rangos CIDR, IPs) se resuelve en la etapa de **Pre requisitos**
+— nunca se lo preguntes al humano campo por campo, usa el archivo de
+configuración (ver abajo).
+
+## Antes de todo: ¿dónde estás parado?
+
+Todos los scripts de este skill asumen que el directorio de trabajo
+(`cwd`) es la **raíz del repo destino** (donde vive `./live/`). Si no
+estás ahí, `cd` primero — cada script valida esto y se detiene con un
+mensaje claro si no es así.
+
+---
+
+## Etapa 1 — Pre requisitos
+
+### 1.1 Generar/localizar el archivo de configuración
+
+```bash
+.claude/skills/kcreate-scaffolding-gcp-script/scripts/01_init_config.sh <SOURCE_ENV> <NEW_ENV>
+```
+
+Este script:
+- Valida que `SOURCE_ENV` exista.
+- Si `live/<NEW_ENV>/` ya existe pero **no hay** config de este skill
+  para esa ejecución: si `project.hcl` ahí tiene `project_id` igual a
+  `NEW_ENV` (la firma que este skill siempre deja), es un **rescate**
+  legítimo — el config se perdió (ej. por un `uninstall.sh
+  --clean-gitignore`) — y se regenera desde cero sin pedir confirmación
+  extra. Si no tiene esa firma, es una colisión real (otra cosa ocupa
+  ese nombre), `DETENTE`. Si **sí hay** config → es un reintento
+  legítimo de una corrida anterior (completa o parcial), no un error.
+- Si es la primera vez: genera `.kcreate-scaffolding/<NEW_ENV>.config` a
+  partir de la plantilla (`templates/scaffolding.config.template`) y
+  **autodetecta** del propio `SOURCE_ENV` todo lo que se pueda (org id,
+  billing account, región/zona, owner, organización de GitHub, IPs fijas
+  de `authorized_networks`, versiones de GKE/Postgres actuales). Si hay
+  una mayoría clara entre los entornos reales de `live/` para una IP fija
+  (ej. `cloudadmin`) y `SOURCE_ENV` difiere, adopta el valor mayoritario
+  en vez del de `SOURCE_ENV` (probable typo) y avisa.
+- Si ya existe (ejecución anterior interrumpida): no lo regenera —
+  reanuda tal cual quedó.
+
+Termina con exit code **0** (`CONFIG_READY`) o **2** (`CONFIG_PENDING`,
+con la lista exacta de campos que faltan).
+
+SI exit code es 2 → muestra al humano exactamente los campos listados
+(`APP_GITHUB_REPO` y `TRACKING_GITHUB_PROJECT_URL` casi siempre — son los
+dos que ningún entorno existente puede responder por sí solo) y pídeselos.
+Edítalos tú mismo en el archivo (son líneas `CLAVE="valor"` simples) y
+vuelve a correr este mismo script para confirmar que ya quedó completo.
+No inventes estos valores ni asumas un repo de GitHub por el nombre de
+`NEW_ENV`.
+
+SI exit code es distinto de 0 y 2 → es un error de validación real
+(`SOURCE_ENV` no existe, `NEW_ENV` ya existe, patrón inválido). `DETENTE`
+y reporta el mensaje tal cual.
+
+Antes de confirmar, revisa también `GKE_VERSION_NEEDS_VERIFICATION` y
+`DATABASE_VERSION_NEEDS_VERIFICATION` en el config: son la versión que ya
+usaba `SOURCE_ENV`, no necesariamente la más reciente. Verifícalas contra
+la documentación oficial de GKE (canal Stable) y Cloud SQL Postgres antes
+de dar por buena la confirmación — si `SOURCE_ENV` es un entorno viejo,
+puede estar desactualizado.
+
+### 1.2 Mostrar y confirmar
+
+```bash
+.claude/skills/kcreate-scaffolding-gcp-script/scripts/02_print_config.sh <NEW_ENV>
+```
+
+Antes de imprimir el config, este script corre un "doctor" sobre
+`SOURCE_ENV`: compara `project_services`/`org_policies`/IP de
+`cloudadmin` contra el resto de `live/` y emite `[WARN]` si `SOURCE_ENV`
+le falta algo que el entorno más reciente (o la mayoría) ya tiene — por
+ejemplo, una API de organización forzada después de que `SOURCE_ENV` se
+creó. **Repórtalas al humano junto con el config** — son parte de lo que
+tiene que confirmar, no ruido a ignorar.
+
+Luego muestra el archivo completo. **Cópialo tal cual al humano** (WARN
+incluidos) y pregúntale textualmente si los datos son correctos.
+
+- SI dice que **no** → `DETENTE` por completo. No corrijas nada por tu
+  cuenta, no sigas a la Etapa 2. Pide que te diga qué está mal, edita
+  exactamente eso, y vuelve a mostrar el archivo completo para una
+  confirmación nueva.
+- SI dice que **sí** → continúa a la Etapa 2.
+
+---
+
+## Etapa 2 — Construcción
+
+```bash
+.claude/skills/kcreate-scaffolding-gcp-script/scripts/10_build_components.sh <NEW_ENV>
+```
+
+Un solo comando. Internamente:
+1. Descubre los componentes de `SOURCE_ENV` (cualquier subcarpeta con
+   `terragrunt.hcl`) y los filtra a solo los **base** (los que existen en
+   TODOS los entornos reales de `live/`) más lo que `EXTRA_COMPONENTS` del
+   config pida explícitamente. Componentes opcionales de `SOURCE_ENV`
+   (`cloud_armor`, `secrets`, etc.) quedan excluidos por defecto — si
+   `NEW_ENV` sí los necesita, agrégalos a `EXTRA_COMPONENTS` en el config
+   y vuelve a correr este script.
+2. Arranca o reanuda el seguimiento con `github-proyect-tracking`. Esto es
+   **best-effort**: si falla (sin red, token, URL inválida), avisa con
+   `[WARN]` y la construcción sigue igual, solo que sin reanudación
+   remota — nunca se detiene por esto.
+3. Copia y adapta cada componente con sustituciones de texto
+   determinísticas — nunca con juicio del agente. El detalle de qué hace
+   cada componente está en `references/lessons-learned.md`.
+4. Corre `terragrunt hcl fmt` + `terragrunt hcl validate` por componente al
+   final (si `terragrunt` está instalado; si no, lo avisa pero no falla
+   por eso). El falso positivo conocido de `gke_private` se tolera; cualquier
+   otro error de `hcl validate` sí detiene la construcción.
+
+Termina con **exactamente uno** de estos mensajes:
+- `BUILD_OK: <ruta>` (exit 0) → continuar a la Etapa 3.
+- `BUILD_FAILED: <paso> - <detalle>` (exit 1) → `DETENTE`. El detalle ya
+  trae lo necesario para decidir si es corregible (edita el archivo de
+  configuración o el `terragrunt.hcl` de `SOURCE_ENV` según corresponda) y
+  vuelve a correr el mismo comando — **es seguro reintentar incluso si
+  `live/<NEW_ENV>/` ya quedó parcialmente creado**: cada componente se
+  reconstruye siempre desde cero a partir de `SOURCE_ENV`, nunca se
+  acumula sobre lo que ya había.
+
+Durante la construcción vas a ver líneas `[WARN]` para los casos que **no**
+se pueden resolver solo con sustitución de texto (bindings de
+`project_iam` específicos de `SOURCE_ENV`, componentes opcionales
+incluidos vía `EXTRA_COMPONENTS` sin manejo dedicado, más de un repo en
+`github_workload_identity` cuando `APP_GITHUB_REPO` tiene varios,
+`artifact_registry` ya genérico en `SOURCE_ENV`, el dominio de
+`dns_domain_name` cuando `DNS_DOMAIN` no está definido en el config,
+claves HCL duplicadas heredadas de `SOURCE_ENV`, componentes excluidos por
+defecto, fallas de tracking). Estas líneas **no son un fallo** — son el
+agente diciéndote exactamente qué revisar a mano antes de confiar en el
+resultado. Quedan también en `.kcreate-scaffolding/<NEW_ENV>.warnings` por
+si la sesión se interrumpe. Léelas todas y repórtalas al humano junto con
+el resultado final; no las descartes en silencio.
+
+---
+
+## Etapa 3 — Validación
+
+Dos scripts, cualquier orden, ambos obligatorios antes de dar por bueno
+el resultado:
+
+```bash
+.claude/skills/kcreate-scaffolding-gcp-script/scripts/20_validate_file_parity.sh <SOURCE_ENV> <NEW_ENV>
+.claude/skills/kcreate-scaffolding-gcp-script/scripts/21_validate_project_pinning.sh <NEW_ENV>
+```
+
+- `20_validate_file_parity.sh` → `FILE_PARITY_OK` (exit 0) o
+  `FILE_PARITY_MISMATCH` (exit 1, con el detalle de qué archivo falta o
+  sobra). Compara solo los archivos que el repo realmente comitearía
+  (respeta `.gitignore`), no cuenta cache ni temporales.
+- `21_validate_project_pinning.sh` → `PROJECT_PINNING_OK` (exit 0) o
+  `PROJECT_PINNING_FAILED` (exit 1, listando cada componente con
+  problema). Confirma que, sin importar qué proyecto tenga `gcloud` como
+  default en ese momento, cada componente de `NEW_ENV` resuelve siempre al
+  proyecto correcto.
+
+SI cualquiera de los dos falla → `DETENTE`. No es un error de Terragrunt
+ni de GCP — es un defecto de generación real, y el mensaje ya dice
+exactamente qué componente/archivo revisar.
+
+SI ambos pasan y el tracking SÍ se inicializó en la Etapa 2 (no viste el
+`[WARN]` de "no se pudo inicializar github-proyect-tracking") → marca el
+proceso como terminado:
+
+```bash
+.claude/skills/kcreate-scaffolding-gcp-script/scripts/run_tracking.sh finalize "$(ls -d .kcreate-scaffolding/<NEW_ENV>.config)"
+```
+
+SI el tracking nunca se inicializó (modo best-effort sin éxito, ver
+Etapa 2) → omite este paso. No hay Issue que cerrar, y `finalize` fallaría
+con un error que no es necesario interpretar ni reportar como problema.
+
+Y reporta al humano:
+1. Que `live/<NEW_ENV>/` quedó generado y validado.
+2. La lista completa de `[WARN]` que salieron durante la Etapa 2 (son los
+   puntos que SÍ requieren una revisión humana antes de desplegar).
+3. Que nada se comiteó — este skill nunca hace `git add`/`git commit` por
+   su cuenta.
+4. Que el siguiente paso (desplegar en GCP) es un proceso separado, fuera
+   del alcance de este skill.
+
+---
+
+## Qué hacer si algo falla a medias
+
+Los scripts de las etapas 1 y 2 son seguros de reintentar:
+`01_init_config.sh` nunca regenera un config que ya existe, y
+`10_build_components.sh` **nunca falla por que `live/<NEW_ENV>/` ya
+exista** — cada componente se reconstruye siempre desde `SOURCE_ENV`
+desde cero, así que un reintento después de un fallo a medias produce el
+mismo resultado que si hubiera corrido bien la primera vez (el rango CIDR
+elegido también se reusa desde `.kcreate-scaffolding/<NEW_ENV>.cidr`, no
+se recalcula). Si la sesión se cae a la mitad de la Etapa 2, simplemente
+vuelve a correr `10_build_components.sh <NEW_ENV>` de nuevo.
+
+Si necesitas descartar un intento fallido por completo y empezar de cero:
+borra `live/<NEW_ENV>/` y `.kcreate-scaffolding/<NEW_ENV>.*` tú mismo (este
+skill nunca borra nada automáticamente) y vuelve a empezar desde la Etapa
+1. Pide confirmación explícita al humano antes de borrar — puede que
+quiera revisar lo que ya se generó en vez de descartarlo.