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

package/skill/scripts/10_build_components.sh

@@ -0,0 +1,596 @@
+#!/usr/bin/env bash
+# Etapa: Construcción.
+# Genera live/<NEW_ENV>/ completo a partir de live/<SOURCE_ENV>/, usando
+# solo sustituciones de texto deterministas (nunca una edición "a mano" por
+# el agente). Cada paso se registra con github-proyect-tracking para poder
+# reanudar si el proceso se interrumpe — pero el tracking es un plus, no un
+# requisito: si falla, el build sigue y queda solo sin reanudación remota
+# (ver Review V1, E-6/E-8).
+#
+# Uso: 10_build_components.sh <NEW_ENV>
+#
+# Termina con exactamente uno de estos mensajes, para que el agente no
+# tenga que interpretar nada:
+#   "BUILD_OK: <ruta>"            (exit 0)
+#   "BUILD_FAILED: <paso> - <detalle>"  (exit 1)
+#
+# Es seguro reintentar: cada build_component_* copia SIEMPRE desde
+# SOURCE_DIR (nunca incrementa sobre lo que ya había en NEW_DIR), así que
+# volver a correr este script después de un fallo a medias reconstruye
+# cada componente desde cero con el mismo resultado — no hace falta un
+# motor de reanudación por paso (Review V1, E-1/faltante #1: la versión
+# anterior SÍ moría en el reintento porque un `mkdir -p "$NEW_DIR"` previo
+# dejaba el directorio creado, y una guarda posterior lo trataba como "ya
+# existe, no tocar". Esa guarda se quitó: ya no es necesaria).
+
+set -uo pipefail  # sin -e: queremos capturar el fallo de un paso y reportarlo via tracking antes de salir
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+source "$SCRIPT_DIR/lib/common.sh"
+
+ksc_require_cmd python3 git curl sed
+
+NEW_ENV="${1:-}"
+[[ -n "$NEW_ENV" ]] || ksc_die "uso: 10_build_components.sh <NEW_ENV>"
+
+REPO_ROOT="$(ksc_repo_root)"
+CONFIG_FILE="$(ksc_config_path "$REPO_ROOT" "$NEW_ENV")"
+[[ -f "$CONFIG_FILE" ]] || ksc_die "no existe $CONFIG_FILE — corre primero 01_init_config.sh y 02_print_config.sh"
+PENDING=$(ksc_config_pending_fields "$CONFIG_FILE" || true)
+[[ -z "$PENDING" ]] || ksc_die "el config todavía tiene campos __PENDIENTE__ — no se construye nada hasta que esté completo y confirmado (02_print_config.sh)."
+
+# shellcheck disable=SC1090
+source "$CONFIG_FILE"
+
+SOURCE_DIR="$REPO_ROOT/live/$SOURCE_ENV"
+NEW_DIR="$REPO_ROOT/live/$NEW_ENV"
+[[ -d "$NEW_DIR" ]] && ksc_info "$NEW_DIR ya existe (reintento) — se reconstruye cada componente desde $SOURCE_ENV, no se acumula sobre lo que ya había."
+
+read -r APP_SOURCE ENTORNO_SOURCE < <(ksc_split_env "$SOURCE_ENV")
+read -r APP_NEW ENTORNO_NEW < <(ksc_split_env "$NEW_ENV")
+APP_NEW_CAP="$(ksc_capitalize "$APP_NEW")"
+
+CIDR_FILE="$(ksc_cidr_file_path "$REPO_ROOT" "$NEW_ENV")"
+PLAN_FILE="$(dirname "$CONFIG_FILE")/${NEW_ENV}.plan.json"
+# Archivo propio de la Construcción, SEPARADO del del doctor
+# (ksc_warnings_file_path, que llena 02_print_config.sh) — Review V3
+# (P-3): compartir un solo archivo en modo append hacía que cada
+# reintento de este script repitiera sus propios WARN sobre los de la
+# corrida anterior, inflando el archivo sin límite. Este SÍ se trunca al
+# inicio de cada corrida (no repite sus propios WARN en un retry); el
+# del doctor nunca se toca aquí, así que sigue intacto entre 02 y 10.
+DOCTOR_WARNINGS_FILE="$(ksc_warnings_file_path "$REPO_ROOT" "$NEW_ENV")"
+export KSC_WARNINGS_FILE="$(ksc_build_warnings_file_path "$REPO_ROOT" "$NEW_ENV")"
+: > "$KSC_WARNINGS_FILE"
+
+# (El "doctor" de SOURCE_ENV ya corrió en 02_print_config.sh, antes de que
+# el humano confirmara — no se repite aquí.)
+
+# ---------------------------------------------------------------------------
+# Qué componentes se construyen: la base (intersección real de todos los
+# entornos de live/, sin lista hardcodeada) + lo que EXTRA_COMPONENTS del
+# config pida explícitamente. Antes se copiaba TODO lo que SOURCE_ENV
+# tuviera, incluyendo opcionales (cloud_armor, secrets, etc.) — Review V1
+# señaló que la guía (§1.2) pide no incluirlos salvo pedido explícito.
+# ---------------------------------------------------------------------------
+mapfile -t SOURCE_COMPONENTS < <(ksc_discover_components "$SOURCE_DIR")
+[[ ${#SOURCE_COMPONENTS[@]} -gt 0 ]] || ksc_die "no se encontró ningún componente (subcarpeta con terragrunt.hcl) en $SOURCE_DIR"
+
+mapfile -t BASE_COMPONENTS < <(ksc_base_components "$REPO_ROOT" "$NEW_ENV")
+IFS=';' read -ra EXTRA_LIST <<<"${EXTRA_COMPONENTS:-}"
+
+COMPONENTS=()
+EXCLUDED=()
+for c in "${SOURCE_COMPONENTS[@]}"; do
+  is_base=0; is_extra=0
+  for b in "${BASE_COMPONENTS[@]}"; do [[ "$c" == "$b" ]] && is_base=1 && break; done
+  for x in "${EXTRA_LIST[@]}"; do [[ -n "$x" && "$c" == "$x" ]] && is_extra=1 && break; done
+  if [[ "$is_base" -eq 1 || "$is_extra" -eq 1 ]]; then
+    COMPONENTS+=("$c")
+  else
+    EXCLUDED+=("$c")
+  fi
+done
+if [[ ${#EXCLUDED[@]} -gt 0 ]]; then
+  ksc_warn "componentes de $SOURCE_ENV excluidos por defecto (no son base y no están en EXTRA_COMPONENTS del config): ${EXCLUDED[*]}. Si NEW_ENV sí los necesita, agrégalos a EXTRA_COMPONENTS en $CONFIG_FILE y vuelve a correr este script."
+fi
+
+# vpc debe ir primero si existe: sql_private_access (y en principio
+# cualquier otro componente que use rangos CIDR) depende del archivo que
+# vpc genera, y el orden de descubrimiento es alfabético, no de
+# dependencias.
+if printf '%s\n' "${COMPONENTS[@]}" | grep -qx vpc; then
+  REORDERED=(vpc)
+  for c in "${COMPONENTS[@]}"; do
+    [[ "$c" == "vpc" ]] && continue
+    REORDERED+=("$c")
+  done
+  COMPONENTS=("${REORDERED[@]}")
+fi
+
+ksc_info "componentes a construir (orden): ${COMPONENTS[*]}"
+
+mkdir -p "$NEW_DIR"
+
+# ---------------------------------------------------------------------------
+# Plan de pasos para tracking + arranque/reanudación. El tracking es
+# best-effort: si falla, se avisa y se sigue sin él (Review V1 E-6/E-8 — la
+# versión anterior moría si no podía inicializar tracking, aunque la
+# construcción es 100% local).
+# ---------------------------------------------------------------------------
+{
+  printf '['
+  printf '"project.hcl",'
+  printf '"top-level-files",'
+  for c in "${COMPONENTS[@]}"; do printf '"%s",' "$c"; done
+  printf '"fmt"'
+  printf ']'
+} > "$PLAN_FILE"
+
+TRACKING_OK=1
+if ! "$SCRIPT_DIR/run_tracking.sh" resume "$CONFIG_FILE" >/tmp/ksc_resume.$$ 2>&1; then
+  if "$SCRIPT_DIR/run_tracking.sh" init-plan "$CONFIG_FILE" "$PLAN_FILE" >/tmp/ksc_init.$$ 2>&1; then
+    ksc_info "tracking iniciado."
+  else
+    TRACKING_OK=0
+    ksc_warn "no se pudo inicializar github-proyect-tracking ($(tail -c 300 /tmp/ksc_init.$$ | tr '\n' ' ')) — la construcción sigue de todas formas, sin reanudación remota. Revisa TRACKING_GITHUB_PROJECT_URL/credenciales y vuelve a correr este script más tarde si quieres recuperar el tracking."
+  fi
+  rm -f /tmp/ksc_init.$$
+else
+  ksc_info "reanudando ejecución existente:"
+  cat /tmp/ksc_resume.$$
+fi
+rm -f /tmp/ksc_resume.$$
+
+step_start() {
+  [[ "$TRACKING_OK" -eq 1 ]] || return 0
+  "$SCRIPT_DIR/run_tracking.sh" step-start "$CONFIG_FILE" "$1" >/tmp/ksc_track.$$ 2>&1 \
+    || ksc_warn "tracking: no se pudo registrar el inicio de '$1' ($(tail -c 200 /tmp/ksc_track.$$ | tr '\n' ' ')) — el paso se ejecuta igual."
+  rm -f /tmp/ksc_track.$$
+}
+step_done() {
+  [[ "$TRACKING_OK" -eq 1 ]] || return 0
+  "$SCRIPT_DIR/run_tracking.sh" step-done "$CONFIG_FILE" "$1" >/tmp/ksc_track.$$ 2>&1 \
+    || ksc_warn "tracking: no se pudo registrar el fin de '$1' ($(tail -c 200 /tmp/ksc_track.$$ | tr '\n' ' ')) — el Issue puede quedar desincronizado."
+  rm -f /tmp/ksc_track.$$
+}
+step_fail() {
+  [[ "$TRACKING_OK" -eq 1 ]] && "$SCRIPT_DIR/run_tracking.sh" step-error "$CONFIG_FILE" "$1" "$2" >/dev/null 2>&1
+  echo "BUILD_FAILED: $1 - $2"
+  exit 1
+}
+
+ksc_copy_component_files() {
+  local comp="$1" f
+  mkdir -p "$NEW_DIR/$comp"
+  for f in Makefile .gitignore terragrunt.hcl; do
+    [[ -f "$SOURCE_DIR/$comp/$f" ]] && cp "$SOURCE_DIR/$comp/$f" "$NEW_DIR/$comp/$f"
+  done
+  # Sustitución estándar aplicada a TODO componente, conocido o no: el
+  # token completo del entorno, y el nombre corto de la app en CUALQUIER
+  # capitalización (ver ksc_substr_replace_app). Antes esto solo se hacía
+  # a mano en algunos componentes — Review V1 (E-5) encontró texto real
+  # de SOURCE_ENV filtrado en service_accounts (display_name) y
+  # project_iam (namespace de un principal) porque esos dos nunca
+  # aplicaban la sustitución de nombre de app, solo la del token
+  # completo. Corregido ahí; después, un bug real encontrado usando el
+  # skill (no en revisión) mostró que la sustitución de nombre de app
+  # EXISTÍA pero solo cubría dos capitalizaciones exactas (minúscula y
+  # "Primera-mayúscula") — un nombre de marca estilizado como "XoloShop"
+  # (S interna mayúscula) no hacía match con ninguna de las dos y se
+  # colaba completo a service_accounts.display_name/description. Ver
+  # lessons-learned.md, sección F.
+  f="$NEW_DIR/$comp/terragrunt.hcl"
+  [[ -f "$f" ]] || return 0
+  ksc_substr_replace "$f" "$SOURCE_ENV" "$NEW_ENV"
+  if [[ "$APP_SOURCE" != "$APP_NEW" ]]; then
+    ksc_substr_replace_app "$f" "$APP_SOURCE" "$APP_NEW"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# project.hcl (no es un "componente" con terragrunt.hcl propio)
+# ---------------------------------------------------------------------------
+build_project_hcl() {
+  cp "$SOURCE_DIR/project.hcl" "$NEW_DIR/project.hcl"
+  local f="$NEW_DIR/project.hcl"
+  ksc_set_key "$f" "project_id" "$NEW_ENV"
+  ksc_set_key "$f" "project_number" ""
+}
+
+# Archivos a nivel raíz de live/<entorno>/ (no de un componente): un
+# Makefile genérico que corre `terragrunt run --all` y un README con la
+# descripción del entorno. Se detectaron ausentes incluso en xoloshop-qa
+# (generado a mano en una sesión anterior) — fácil de olvidar si no queda
+# como un paso explícito de la construcción. Que SOURCE_ENV no tenga
+# alguno de estos 3 archivos es normal, NO un error (Review V1, E-3: la
+# versión anterior fallaba la construcción completa cuando faltaba
+# cualquiera de los 3, justo el caso de xoloshop-qa).
+build_top_level_files() {
+  local f
+  for f in Makefile README.md .gitignore; do
+    if [[ -f "$SOURCE_DIR/$f" ]]; then
+      cp "$SOURCE_DIR/$f" "$NEW_DIR/$f" || return 1
+    fi
+  done
+  if [[ -f "$NEW_DIR/README.md" ]]; then
+    ksc_substr_replace "$NEW_DIR/README.md" "$SOURCE_ENV" "$NEW_ENV"
+  fi
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# Componentes con manejo específico (ver referencias/lessons-learned.md
+# para el porqué de cada uno).
+# ---------------------------------------------------------------------------
+build_component_project() {
+  ksc_copy_component_files project
+  local f="$NEW_DIR/project/terragrunt.hcl"
+  ksc_set_key "$f" "project_name" "$PROJECT_NAME"
+  ksc_set_key "$f" "org_id" "$ORG_ID"
+  ksc_set_key "$f" "org_billing_account" "$ORG_BILLING_ACCOUNT"
+  ksc_set_key "$f" "project" "$APP_NEW"
+  ksc_set_key "$f" "environment" "$ENTORNO_NEW"
+  ksc_set_key "$f" "owner" "$LABEL_OWNER"
+}
+
+build_component_project_services() {
+  ksc_copy_component_files project_services
+  # La lista de APIs se copia tal cual (sin editarla a mano: así se
+  # elimina por diseño el bug real de "coma faltante"). El doctor
+  # (ksc_check_source_health, corrido antes de construir) ya avisó si a
+  # SOURCE_ENV le falta algo que el entorno más reciente de live/ sí
+  # tiene — aquí no se vuelve a repetir esa lógica.
+}
+
+build_component_org_policies() {
+  ksc_copy_component_files org_policies
+  # Igual que project_services: se copia tal cual, el doctor ya avisó si
+  # SOURCE_ENV tiene menos entradas que el entorno más reciente de live/.
+}
+
+build_component_service_accounts() {
+  ksc_copy_component_files service_accounts
+  local f="$NEW_DIR/service_accounts/terragrunt.hcl"
+  local n
+  n="$(grep -c 'account_id[[:space:]]*=' "$f")"
+  if [[ "$n" -gt 5 ]]; then
+    ksc_warn "service_accounts de $SOURCE_ENV tiene $n entradas (más de las 5 estándar: terraform, github-manager, gke-sa-external-secrets, <app>-node-sa, <app>-bastion-sa) — revisa a mano si las SAs extra son específicas de $SOURCE_ENV y no deberían existir en $NEW_ENV."
+  fi
+}
+
+build_component_project_iam() {
+  ksc_copy_component_files project_iam
+  local f="$NEW_DIR/project_iam/terragrunt.hcl"
+  # Se ignoran líneas de comentario: xoloshop-qa real tiene un comentario
+  # explicando por qué NO se puede usar roles/orgpolicy.policyAdmin aquí
+  # (precisamente la lección que este chequeo busca aplicar) — ese
+  # comentario mencionaba el string textualmente y disparaba un falso
+  # BUILD_FAILED real al probar esto con xoloshop-qa como SOURCE_ENV.
+  if grep -v '^[[:space:]]*#' "$f" | grep -q "orgpolicy.policyAdmin"; then
+    step_fail "project_iam" "el archivo copiado de $SOURCE_ENV incluye roles/orgpolicy.policyAdmin fuera de un comentario, que GCP rechaza a nivel proyecto. Quítalo de live/$SOURCE_ENV/project_iam/terragrunt.hcl primero."
+  fi
+  # Guía §3.12: dejar un comentario EN EL ARCHIVO, no solo en la consola,
+  # para que una revisión futura del propio HCL no asuma que faltó por
+  # descuido (Review V1, faltante #12).
+  python3 - "$f" "$SOURCE_ENV" <<'PYEOF'
+import sys
+file, source_env = sys.argv[1], sys.argv[2]
+marker = "# NOTA kcreate-scaffolding-gcp-script: este archivo se copió completo de\n# live/" + source_env + "/project_iam/terragrunt.hcl SIN filtrar. Revisa a mano si\n# incluye bindings especificos de esa app/equipo (dominios externos,\n# roles personalizados) que NO deberian existir aqui.\n"
+with open(file) as fh:
+    text = fh.read()
+if marker not in text:
+    text = text.replace("inputs = {", marker + "inputs = {", 1)
+with open(file, "w") as fh:
+    fh.write(text)
+PYEOF
+  ksc_warn "project_iam copiado de $SOURCE_ENV sin filtrar — revisa a mano que no haya bindings específicos del equipo/app de $SOURCE_ENV (dominios externos, roles personalizados) antes de confiar en este archivo (queda anotado también dentro del propio archivo)."
+}
+
+build_component_vpc() {
+  ksc_copy_component_files vpc
+  local f="$NEW_DIR/vpc/terragrunt.hcl"
+
+  local subnet pods svc priv
+  if [[ -f "$CIDR_FILE" ]]; then
+    # Reintento: ya se había elegido un rango en una corrida anterior —
+    # reusarlo en vez de recalcular (determinismo; Review V1 E-1/E-2
+    # mencionan la importancia de que un reintento no produzca un
+    # resultado distinto).
+    ksc_info "reusando rango CIDR ya elegido en $CIDR_FILE (de una corrida anterior)."
+    subnet="$(sed -n 1p "$CIDR_FILE")"; pods="$(sed -n 2p "$CIDR_FILE")"
+    svc="$(sed -n 3p "$CIDR_FILE")"; priv="$(sed -n 4p "$CIDR_FILE")"
+  else
+    local existing_file="/tmp/ksc_existing_cidrs.$$"
+    # vpc/terragrunt.hcl ya guarda sus 3 rangos en notación CIDR completa
+    # ("x.x.x.x/nn"). sql_private_access, en cambio, guarda `address` sin
+    # sufijo y `prefix_length` aparte — hay que recombinarlos, si no, el
+    # picker nunca ve esos /16 como ocupados y podría asignar algo que
+    # colisiona con un sql_private_access existente.
+    grep -rhoE '"[0-9]{1,3}(\.[0-9]{1,3}){3}/[0-9]{1,2}"' "$REPO_ROOT"/live/*/vpc/terragrunt.hcl 2>/dev/null \
+      | tr -d '"' > "$existing_file"
+    local sp_file addr prefix
+    for sp_file in "$REPO_ROOT"/live/*/sql_private_access/terragrunt.hcl; do
+      [[ -f "$sp_file" ]] || continue
+      addr="$(ksc_hcl_get "$sp_file" address)"
+      prefix="$(ksc_hcl_get "$sp_file" prefix_length)"
+      [[ -n "$addr" && -n "$prefix" ]] && echo "${addr}/${prefix}" >> "$existing_file"
+    done
+
+    local cidrs
+    cidrs="$(ksc_cidr_pick_free "$existing_file")" || step_fail "vpc" "no se encontró un rango CIDR libre (ver $existing_file)"
+    rm -f "$existing_file"
+    subnet="$(sed -n 1p <<<"$cidrs")"; pods="$(sed -n 2p <<<"$cidrs")"
+    svc="$(sed -n 3p <<<"$cidrs")"; priv="$(sed -n 4p <<<"$cidrs")"
+    printf '%s\n%s\n%s\n%s\n' "$subnet" "$pods" "$svc" "$priv" > "$CIDR_FILE"
+  fi
+  ksc_ok "rangos CIDR para $NEW_ENV: subred=$subnet pods=$pods svc=$svc sql_private_access=$priv"
+
+  ksc_replace_nth "$f" 'ip_cidr_range\s*=\s*"([^"]*)"' 1 "$subnet" || return 1
+  ksc_replace_nth "$f" 'ip_cidr_range\s*=\s*"([^"]*)"' 2 "$pods" || return 1
+  ksc_replace_nth "$f" 'ip_cidr_range\s*=\s*"([^"]*)"' 3 "$svc" || return 1
+}
+
+build_component_firewall() {
+  ksc_copy_component_files firewall
+}
+
+build_component_sql_private_access() {
+  ksc_copy_component_files sql_private_access
+  local f="$NEW_DIR/sql_private_access/terragrunt.hcl"
+  [[ -f "$CIDR_FILE" ]] || step_fail "sql_private_access" "falta $CIDR_FILE — el paso 'vpc' debe correr antes."
+  local priv priv_addr priv_prefix
+  priv="$(sed -n 4p "$CIDR_FILE")"
+  priv_addr="${priv%%/*}"
+  priv_prefix="${priv##*/}"
+  # El módulo guarda la dirección sin sufijo y el prefijo en un campo
+  # separado (ver live/*/sql_private_access/terragrunt.hcl real) — nunca
+  # "x.x.x.x/16" junto en un solo campo.
+  ksc_set_key "$f" "address" "$priv_addr"
+  ksc_set_key "$f" "prefix_length" "$priv_prefix"
+}
+
+build_component_sql_postgres() {
+  ksc_copy_component_files sql_postgres
+  local f="$NEW_DIR/sql_postgres/terragrunt.hcl"
+  ksc_set_key "$f" "name" "$APP_NEW"
+  ksc_set_key "$f" "label_project" "$APP_NEW"
+  ksc_set_key "$f" "label_environment" "$ENTORNO_NEW"
+  ksc_set_key "$f" "label_owner" "$LABEL_OWNER"
+  ksc_set_key "$f" "database_version" "$DATABASE_VERSION_NEEDS_VERIFICATION"
+
+  # Guía §3.9: deletion_protection* debe ser "true" en *-prod, confirmar
+  # con el humano. Antes se copiaba de SOURCE_ENV sin aviso — si SOURCE_ENV
+  # es qa (="false") y NEW_ENV es prod, el generado quedaba "false" en
+  # prod sin que nadie lo notara (Review V1, E-4/faltante #11).
+  if [[ "$ENTORNO_NEW" == "prod" ]]; then
+    local dp dpe
+    dp="$(ksc_hcl_get "$f" deletion_protection)"
+    dpe="$(ksc_hcl_get "$f" deletion_protection_enabled)"
+    if [[ "$dp" == "false" || "$dpe" == "false" ]]; then
+      ksc_warn "NEW_ENV es *-prod pero deletion_protection/deletion_protection_enabled quedaron en \"false\" (heredado de $SOURCE_ENV) — la guía pide \"true\" en prod. Confirma con el humano y corrige $f si aplica."
+    fi
+  fi
+
+  local dev_ip dev_user
+  dev_ip="$(ksc_fresh_public_ip)"
+  dev_user="$(id -un)"
+  local entries="${FIXED_ADMIN_NETWORKS};dev-${dev_user}=${dev_ip}/32"
+  ksc_set_authorized_networks "$f" "$entries" || return 1
+  ksc_ok "authorized_networks: fijas=[$FIXED_ADMIN_NETWORKS] + dev-${dev_user}=${dev_ip}/32 (IP obtenida ahora, no reusada)"
+
+  # dns_record_name/dns_domain_name son opcionales (algunos entornos no los
+  # tienen). dns_record_name sigue un patrón seguro de generar siempre
+  # (<app>.db, no depende de qué dominio sea dueño nadie). dns_domain_name
+  # SÍ codifica un dominio real registrado (ej. "boletera.ninja") — si el
+  # humano ya lo confirmó en DNS_DOMAIN (config), se usa ese valor
+  # directo, sin WARN; si no, se genera un valor por patrón y SIEMPRE se
+  # marca para confirmación (Review V1, mejora #7).
+  if grep -q '^[[:space:]]*dns_record_name[[:space:]]*=' "$f"; then
+    ksc_set_key "$f" "dns_record_name" "${APP_NEW}.db"
+    if [[ -n "${DNS_DOMAIN:-}" ]]; then
+      ksc_set_key "$f" "dns_domain_name" "$DNS_DOMAIN"
+      ksc_ok "dns_domain_name = \"$DNS_DOMAIN\" (confirmado en DNS_DOMAIN del config, no es un guess)."
+    else
+      local dns_domain_guess
+      if [[ "$ENTORNO_NEW" == "qa" ]]; then
+        dns_domain_guess="qa.${APP_NEW}.ninja."
+      else
+        dns_domain_guess="${APP_NEW}.ninja."
+      fi
+      ksc_set_key "$f" "dns_domain_name" "$dns_domain_guess"
+      ksc_warn "dns_domain_name de $f se generó SOLO por patrón visual ($dns_domain_guess, copiando la convención de $SOURCE_ENV) porque DNS_DOMAIN no está definido en el config. CONFIRMA con el humano que '$APP_NEW' realmente usa ese dominio antes de desplegar — si no, define DNS_DOMAIN en el config y reconstruye."
+    fi
+  fi
+}
+
+build_component_gke_private() {
+  ksc_copy_component_files gke_private
+  local f="$NEW_DIR/gke_private/terragrunt.hcl"
+  ksc_set_key "$f" "label_project" "$APP_NEW"
+  ksc_set_key "$f" "label_environment" "$ENTORNO_NEW"
+  ksc_set_key "$f" "label_owner" "$LABEL_OWNER"
+  ksc_set_key "$f" "gke_version" "$GKE_VERSION_NEEDS_VERIFICATION"
+}
+
+build_component_storage_assets() {
+  ksc_copy_component_files storage_assets
+  local f="$NEW_DIR/storage_assets/terragrunt.hcl"
+  ksc_set_key "$f" "label_project" "$APP_NEW"
+  ksc_set_key "$f" "label_environment" "$ENTORNO_NEW"
+  ksc_set_key "$f" "label_owner" "$LABEL_OWNER"
+}
+
+build_component_storage_docs() {
+  ksc_copy_component_files storage_docs
+  local f="$NEW_DIR/storage_docs/terragrunt.hcl"
+  ksc_set_key "$f" "label_project" "$APP_NEW"
+  ksc_set_key "$f" "label_environment" "$ENTORNO_NEW"
+  ksc_set_key "$f" "label_owner" "$LABEL_OWNER"
+}
+
+build_component_artifact_registry() {
+  # Se decide ANTES de copiar (ksc_copy_component_files ya sustituye
+  # APP_SOURCE->APP_NEW automáticamente): si el archivo de SOURCE_ENV ya
+  # era genérico (sin el nombre de la app), la sustitución automática no
+  # tiene nada que reemplazar y el resultado seguiría siendo genérico.
+  local was_generic=1
+  # -i: la app puede aparecer con cualquier capitalización (ver
+  # ksc_substr_replace_app) — un chequeo exacto-minúscula aquí marcaría
+  # "genérico" un archivo que en realidad sí tiene el nombre de la app
+  # (solo que estilizado, ej. "XoloShop"), y la sustitución automática de
+  # ksc_copy_component_files ya lo habría corregido de todas formas.
+  grep -qi "$APP_SOURCE" "$SOURCE_DIR/artifact_registry/terragrunt.hcl" && was_generic=0
+
+  ksc_copy_component_files artifact_registry
+
+  if [[ "$was_generic" -eq 1 ]]; then
+    local f="$NEW_DIR/artifact_registry/terragrunt.hcl"
+    local template_output id_tpl desc_tpl
+    template_output="$(ksc_learn_artifact_registry_template "$REPO_ROOT")"
+    id_tpl="$(sed -n '1p' <<<"$template_output")"
+    desc_tpl="$(sed -n '2p' <<<"$template_output")"
+    if [[ -n "$id_tpl" ]]; then
+      # Se "aprendió" el patrón de OTRO entorno real que sí tiene su
+      # artifact_registry específico (ej. xoloshop-qa) y se aplica con
+      # el nombre de la app nueva — sin hardcodear ningún literal de la
+      # organización en el código del skill (Review V2, mejora pendiente
+      # de la sección 2.3/4.3).
+      local new_id="${id_tpl//\{\{APP\}\}/$APP_NEW}"
+      local new_desc="${desc_tpl//\{\{APP_CAP\}\}/$APP_NEW_CAP}"
+      new_desc="${new_desc//\{\{APP\}\}/$APP_NEW}"
+      ksc_set_key "$f" "repository_id" "$new_id"
+      ksc_set_key "$f" "description" "$new_desc"
+      ksc_ok "artifact_registry: $SOURCE_ENV tenía valores genéricos; se generaron repository_id/description específicos aprendiendo el patrón de otro entorno real (repository_id=\"$new_id\")."
+    else
+      ksc_warn "artifact_registry de $SOURCE_ENV ya tiene repository_id/description genéricos (no contienen '$APP_SOURCE'), y ningún otro entorno de live/ tiene uno específico del que aprender el patrón. Se copió sin poder adaptar el nombre de la app: corrígelo a mano con valores específicos de $APP_NEW antes de confiar en él."
+    fi
+  fi
+}
+
+build_component_github_workload_identity() {
+  ksc_copy_component_files github_workload_identity
+  local f="$NEW_DIR/github_workload_identity/terragrunt.hcl"
+
+  # El binding de terraform se identifica por contenido
+  # (service_account_email que empieza con "terraform@"), nunca por
+  # posición — Review V1 (E-5/mejora #8) señaló que editar por posición
+  # (la 2.ª coincidencia de principal_set_suffix) corrompería el binding
+  # de infra-cloud si el orden en SOURCE_ENV fuera distinto.
+  #
+  # No todos los entornos reales tienen este binding: cashless-qa real
+  # solo tiene el de github-manager. Si falta, no es un error — se usa
+  # "infra-cloud" por defecto (el valor que la guía §3.15 pide siempre)
+  # y se avisa, en vez de fallar la construcción completa.
+  local terraform_suffix
+  terraform_suffix="$(python3 -c "
+import re
+with open('$f') as fh:
+    text = fh.read()
+m = re.search(r'service_account_email\s*=\s*\"terraform@[^\"]*\"[^}]*principal_set_suffix\s*=\s*\"([^\"]*)\"', text, re.DOTALL)
+print(m.group(1) if m else '')
+")"
+  if [[ -z "$terraform_suffix" ]]; then
+    terraform_suffix="infra-cloud"
+    ksc_warn "github_workload_identity de $SOURCE_ENV no tenía un binding de terraform@... — se agregó uno nuevo con suffix \"infra-cloud\" (necesario para que el CI/CD de este repo opere sobre $NEW_ENV). Confirma que ese es el repo correcto."
+  fi
+
+  # APP_GITHUB_REPO admite uno o varios repos separados por ';' (apps
+  # multi-repo, como boletera-qa con 5 — Review V1 mejora #6). El bloque
+  # completo se reconstruye siempre: terraform (preservando su suffix) +
+  # un binding github-manager por repo. Esto reemplaza por completo el
+  # enfoque anterior de "advertir y no tocar" cuando había más de 2
+  # bindings.
+  local repo_names="" repo entry
+  IFS=';' read -ra _repos <<<"$APP_GITHUB_REPO"
+  for entry in "${_repos[@]}"; do
+    [[ -z "$entry" ]] && continue
+    repo="${entry##*/}"
+    repo_names="${repo_names}${repo_names:+;}${repo}"
+  done
+  [[ -n "$repo_names" ]] || step_fail "github_workload_identity" "APP_GITHUB_REPO está vacío en el config"
+
+  ksc_set_workload_identity_bindings "$f" "$terraform_suffix" "$repo_names" || return 1
+
+  local n_repos
+  n_repos="$(tr ';' '\n' <<<"$repo_names" | grep -c .)"
+  if [[ "$n_repos" -gt 1 ]]; then
+    ksc_warn "github_workload_identity de $NEW_ENV quedó con $n_repos bindings github-manager (uno por repo en APP_GITHUB_REPO) — confirma que esa es la lista completa y correcta de repos de la app."
+  fi
+}
+
+# Fallback genérico para cualquier componente opcional sin manejo
+# específico que de todas formas se incluyó (vía EXTRA_COMPONENTS).
+build_component_generic() {
+  local comp="$1"
+  ksc_copy_component_files "$comp"
+  ksc_warn "'$comp' no tiene manejo específico en este skill (incluido vía EXTRA_COMPONENTS) — se copió con la sustitución estándar de entorno/nombre de app. Revísalo a mano antes de confiar en él."
+}
+
+# ---------------------------------------------------------------------------
+# Ejecución del plan
+# ---------------------------------------------------------------------------
+step_start "project.hcl"
+build_project_hcl || step_fail "project.hcl" "fallo copiando/editando project.hcl"
+step_done "project.hcl"
+
+step_start "top-level-files"
+build_top_level_files || step_fail "top-level-files" "fallo copiando Makefile/README.md/.gitignore de nivel raíz"
+step_done "top-level-files"
+
+for comp in "${COMPONENTS[@]}"; do
+  step_start "$comp"
+  fn="build_component_${comp}"
+  if declare -f "$fn" >/dev/null; then
+    "$fn" || step_fail "$comp" "fallo en $fn"
+  else
+    build_component_generic "$comp" || step_fail "$comp" "fallo en build_component_generic"
+  fi
+  step_done "$comp"
+done
+
+step_start "fmt"
+for comp in "${COMPONENTS[@]}"; do
+  tg="$NEW_DIR/$comp/terragrunt.hcl"
+  [[ -f "$tg" ]] || continue
+  if ! ksc_check_duplicate_keys "$tg" 2>/tmp/ksc_dupe.$$; then
+    ksc_warn "$(cat /tmp/ksc_dupe.$$) (heredado de SOURCE_ENV — terragrunt hcl fmt/validate no lo detectan por sí solos)"
+  fi
+  rm -f /tmp/ksc_dupe.$$
+done
+
+if command -v terragrunt >/dev/null 2>&1; then
+  (cd "$NEW_DIR" && terragrunt hcl fmt --working-dir . >/tmp/ksc_fmt.$$ 2>&1) \
+    || step_fail "fmt" "terragrunt hcl fmt falló: $(cat /tmp/ksc_fmt.$$)"
+  rm -f /tmp/ksc_fmt.$$
+
+  # Guía §3.17: `terragrunt hcl validate` por componente al cerrar la
+  # construcción (antes solo se corría `hcl fmt`; Review V1, faltante
+  # #10). La excepción conocida de gke_private (falso positivo sobre
+  # `dependency.vpc` sin remote state) se tolera; cualquier otro error de
+  # sintaxis real sí detiene la construcción.
+  for comp in "${COMPONENTS[@]}"; do
+    [[ -f "$NEW_DIR/$comp/terragrunt.hcl" ]] || continue
+    if ! (cd "$NEW_DIR/$comp" && terragrunt hcl validate >/tmp/ksc_val.$$ 2>&1); then
+      if grep -q 'does not have an attribute named "outputs"' /tmp/ksc_val.$$; then
+        ksc_info "$comp: falso positivo conocido de 'terragrunt hcl validate' sobre dependency sin remote state (ver lessons-learned.md) — ignorado."
+      else
+        step_fail "fmt" "$comp: terragrunt hcl validate falló: $(cat /tmp/ksc_val.$$)"
+      fi
+    fi
+    rm -f /tmp/ksc_val.$$
+  done
+else
+  ksc_warn "terragrunt no está instalado en este entorno — se omite 'hcl fmt'/'hcl validate' (no es bloqueante, pero córrelos manualmente después)."
+fi
+step_done "fmt"
+
+if [[ -s "$DOCTOR_WARNINGS_FILE" || -s "$KSC_WARNINGS_FILE" ]]; then
+  echo
+  echo "=== WARN acumulados (doctor: $DOCTOR_WARNINGS_FILE + construcción: $KSC_WARNINGS_FILE) ==="
+  [[ -s "$DOCTOR_WARNINGS_FILE" ]] && cat "$DOCTOR_WARNINGS_FILE"
+  [[ -s "$KSC_WARNINGS_FILE" ]] && cat "$KSC_WARNINGS_FILE"
+fi
+
+echo "BUILD_OK: $NEW_DIR"