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

package/skill/scripts/lib/common.sh

@@ -0,0 +1,788 @@
+#!/usr/bin/env bash
+# Funciones compartidas por los scripts numerados de este skill.
+# Se importa con `source`, nunca se ejecuta directamente.
+
+ksc_ok()   { printf '\033[32m[OK]\033[0m %s\n' "$1"; }
+ksc_info() { printf '[INFO] %s\n' "$1"; }
+# Si $KSC_WARNINGS_FILE está definida (10_build_components.sh la fija),
+# cada WARN también se guarda ahí — así sobreviven si la sesión del agente
+# muere a mitad de la construcción (Review V1, faltante #17).
+ksc_warn() {
+  printf '\033[33m[WARN]\033[0m %s\n' "$1"
+  [[ -n "${KSC_WARNINGS_FILE:-}" ]] && printf '%s\n' "$1" >> "$KSC_WARNINGS_FILE"
+  return 0
+}
+ksc_err()  { printf '\033[31m[ERROR]\033[0m %s\n' "$1" >&2; }
+ksc_die()  { ksc_err "$1"; exit 1; }
+
+# ksc_require_cmd <cmd> [<cmd>...] -> DETENTE con mensaje claro si falta
+# alguno. Nunca falla a medias por un `command not found` confuso.
+ksc_require_cmd() {
+  local missing=() c
+  for c in "$@"; do
+    command -v "$c" >/dev/null 2>&1 || missing+=("$c")
+  done
+  [[ ${#missing[@]} -eq 0 ]] || ksc_die "faltan estos comandos requeridos: ${missing[*]}"
+}
+
+# ---------------------------------------------------------------------------
+# Ubicación del repo destino (donde este skill quedó instalado en
+# .claude/skills/kcreate-scaffolding-gcp-script/). Todos los scripts se
+# invocan con el cwd en la raíz de ese repo — lo validamos aquí.
+# ---------------------------------------------------------------------------
+ksc_repo_root() {
+  local root
+  root="$(pwd)"
+  [[ -d "$root/live" ]] || ksc_die \
+    "este script debe correrse desde la raíz del repo destino (debe existir ./live/). cwd actual: $root"
+  [[ -d "$root/.git" ]] || ksc_die "cwd actual no es la raíz de un repo git: $root"
+  printf '%s\n' "$root"
+}
+
+# ---------------------------------------------------------------------------
+# Descubrimiento de componentes: nunca hardcodeado. Un componente es
+# cualquier subdirectorio directo de live/<env>/ que contenga terragrunt.hcl.
+# Esto generaliza el skill a cualquier entorno fuente, con cualquier
+# combinación de componentes (base + opcionales), sin mantener una lista fija.
+# ---------------------------------------------------------------------------
+ksc_discover_components() {
+  local env_dir="$1"
+  [[ -d "$env_dir" ]] || ksc_die "no existe $env_dir"
+  find "$env_dir" -mindepth 1 -maxdepth 1 -type d | sort | while read -r d; do
+    [[ -f "$d/terragrunt.hcl" ]] && basename "$d"
+  done
+}
+
+# ---------------------------------------------------------------------------
+# Lista de entornos "reales" de live/ para cualquier cómputo que compare
+# contra "todo live/" (base de componentes, doctor, mayoría de IPs
+# fijas): solo cuentan los que (a) siguen el patrón <app>-qa|prod> (no
+# "shared" ni otro proyecto de infraestructura compartida) y (b) tienen
+# AL MENOS UN archivo comiteado en git bajo su directorio — este skill
+# nunca comitea nada, así que cualquier intento (completo o parcial,
+# propio o de otro NEW_ENV) queda excluido sin tener que conocer su
+# nombre. `exclude_env` (normalmente $NEW_ENV) se descarta explícito
+# además, por claridad.
+#
+# Consolidado en un solo lugar (Review V2, N-1): la primera corrección
+# solo aplicó este filtro a ksc_base_components; ksc_check_source_health
+# y ksc_majority_fixed_network tenían el mismo filtro incompleto
+# (solo por nombre) y se contaminaban igual con entornos de prueba sin
+# comitear — encontrado probando el fix de N-1 con varios entornos
+# escalonados en la misma copia de prueba.
+# ---------------------------------------------------------------------------
+ksc_real_envs() {
+  local repo_root="$1" exclude_env="${2:-}"
+  local env_dir env_name
+  for env_dir in "$repo_root"/live/*/; do
+    [[ -d "$env_dir" ]] || continue
+    env_name="$(basename "$env_dir")"
+    [[ -n "$exclude_env" && "$env_name" == "$exclude_env" ]] && continue
+    [[ "$env_name" =~ ^[a-z0-9]+-(qa|prod)$ ]] || continue
+    [[ -z "$(cd "$repo_root" && git ls-files -- "live/$env_name/" 2>/dev/null | head -1)" ]] && continue
+    printf '%s\n' "$env_name"
+  done
+}
+
+# ---------------------------------------------------------------------------
+# Componentes "base": los que existen en TODOS los entornos de live/, sin
+# hardcodear nombres (ni "14 componentes", ni la lista de los 4 opcionales
+# de la guía). Un componente que solo existe en algunos entornos (ej.
+# cloud_armor, secrets) queda fuera de la base por definición — exactamente
+# los que la guía (§1.2) pide no incluir salvo pedido explícito. Esto
+# resuelve la desviación real encontrada en Review V1 (sección 3.2, fila
+# §1.2): antes se copiaba cualquier componente que SOURCE_ENV tuviera.
+#
+# ksc_base_components <repo_root> [exclude_env]
+#
+# Review V2 (N-1, CRÍTICO): la intersección contra TODO directorio de
+# live/ que cumpla el patrón de nombre también cuenta un `live/<NEW_ENV>/`
+# a medio construir (justo el estado que deja un reintento, que el fix de
+# E-1 volvió el escenario normal) — y cualquier otra carpeta parcial
+# vieja que haya quedado de un intento abandonado, de CUALQUIER nombre,
+# contamina la base para TODAS las construcciones futuras, no solo la
+# propia. Reproducido: un reintento con un parcial de 2 componentes
+# reconstruía solo esos 2, y `FILE_PARITY_OK`/`PROJECT_PINNING_OK` le
+# daban luz verde igual, porque la validación usa la misma función.
+#
+# Dos capas de defensa, no solo una:
+#   1. `exclude_env` (normalmente $NEW_ENV) nunca cuenta — resuelve la
+#      auto-contaminación del propio reintento.
+#   2. Un entorno solo cuenta si tiene AL MENOS UN archivo comiteado en
+#      git bajo su `live/<env>/` — este skill nunca comitea nada, así
+#      que cualquier intento abandonado (completo o parcial) es, por
+#      definición, 100% no comiteado y queda fuera. Esto resuelve la
+#      contaminación cruzada (un parcial de OTRO entorno, con OTRO
+#      nombre, ya no envenena nada) sin tener que listar nombres
+#      conocidos ni asumir que "bien formado" == "completo".
+# ---------------------------------------------------------------------------
+ksc_base_components() {
+  local repo_root="$1" exclude_env="${2:-}"
+  local base_set=() first=1 d comp env_name
+  local real_envs=()
+  mapfile -t real_envs < <(ksc_real_envs "$repo_root" "$exclude_env")
+  # Review V3 (observación, mejora #6): si no hay NINGÚN entorno
+  # comiteado, `ksc_real_envs` da vacío y la base también quedaría
+  # vacía en silencio — en un repo de infra real esto no pasa (siempre
+  # tiene historia), pero avisa explícito en vez de dejar que el build
+  # excluya todo sin explicación clara.
+  if [[ "${#real_envs[@]}" -eq 0 ]]; then
+    ksc_warn "no hay ningún entorno comiteado en git bajo live/ (¿repo recién creado sin commit inicial, o estás en la raíz equivocada?) — la base de componentes queda vacía; todo se excluirá salvo lo que EXTRA_COMPONENTS pida explícito."
+  fi
+  for env_name in "${real_envs[@]}"; do
+    mapfile -t comps_here < <(ksc_discover_components "$repo_root/live/$env_name")
+    if [[ "$first" -eq 1 ]]; then
+      base_set=("${comps_here[@]}")
+      first=0
+    else
+      local kept=()
+      for comp in "${base_set[@]}"; do
+        for d in "${comps_here[@]}"; do
+          [[ "$comp" == "$d" ]] && { kept+=("$comp"); break; }
+        done
+      done
+      base_set=("${kept[@]}")
+    fi
+  done
+  printf '%s\n' "${base_set[@]}" | sort
+}
+
+# ---------------------------------------------------------------------------
+# Extractor simple de valores escalares de un terragrunt.hcl.
+# Solo sirve para líneas `clave = "valor"` o `clave = valor` (sin
+# expresiones). Si la clave aparece varias veces (ej. dentro de bloques
+# repetidos), devuelve la primera coincidencia — para esos casos usar
+# ksc_hcl_get_all en su lugar.
+# ---------------------------------------------------------------------------
+ksc_hcl_get() {
+  local file="$1" key="$2"
+  [[ -f "$file" ]] || return 1
+  grep -m1 -E "^[[:space:]]*${key}[[:space:]]*=" "$file" \
+    | sed -E 's/^[^=]*=[[:space:]]*//' \
+    | sed -E 's/^"(.*)"[[:space:]]*(#.*)?$/\1/' \
+    | sed -E 's/[[:space:]]*(#.*)?$//'
+}
+
+ksc_hcl_get_all() {
+  local file="$1" key="$2"
+  [[ -f "$file" ]] || return 1
+  grep -E "^[[:space:]]*${key}[[:space:]]*=" "$file" \
+    | sed -E 's/^[^=]*=[[:space:]]*//' \
+    | sed -E 's/^"(.*)"[[:space:]]*(#.*)?$/\1/' \
+    | sed -E 's/[[:space:]]*(#.*)?$//'
+}
+
+# ---------------------------------------------------------------------------
+# PROJECT_NAME inferido de NEW_ENV, según la convención real observada en
+# los entornos existentes (Boletera-QA, Boletera-Prod, Cashless-QA,
+# Xoloshop-QA): <App-con-primera-mayúscula>-<ENTORNO>, donde ENTORNO es
+# "QA" en mayúsculas o "Prod" con mayúscula inicial.
+# ---------------------------------------------------------------------------
+ksc_infer_project_name() {
+  local new_env="$1"
+  local app="${new_env%-*}"
+  local entorno="${new_env##*-}"
+  local app_cap entorno_cap
+  app_cap="$(printf '%s' "${app:0:1}" | tr '[:lower:]' '[:upper:]')${app:1}"
+  case "$entorno" in
+    qa)   entorno_cap="QA" ;;
+    prod) entorno_cap="Prod" ;;
+    *)    entorno_cap="$(printf '%s' "${entorno:0:1}" | tr '[:lower:]' '[:upper:]')${entorno:1}" ;;
+  esac
+  printf '%s-%s\n' "$app_cap" "$entorno_cap"
+}
+
+# ksc_split_env <new_env> -> imprime "app entorno" (separados por espacio)
+ksc_split_env() {
+  local new_env="$1"
+  printf '%s %s\n' "${new_env%-*}" "${new_env##*-}"
+}
+
+# ---------------------------------------------------------------------------
+# IP pública actual, obtenida en el momento (nunca cacheada ni reusada de
+# una ejecución anterior — el ISP del usuario cambia).
+# ---------------------------------------------------------------------------
+ksc_fresh_public_ip() {
+  local ip
+  ip="$(curl -s --max-time 5 https://ifconfig.me 2>/dev/null)"
+  if [[ -z "$ip" ]]; then
+    ip="$(curl -s --max-time 5 https://api.ipify.org 2>/dev/null)"
+  fi
+  [[ -n "$ip" ]] || ksc_die "no se pudo obtener la IP pública actual (ifconfig.me y api.ipify.org fallaron)"
+  printf '%s\n' "$ip"
+}
+
+# ---------------------------------------------------------------------------
+# Validación/cálculo de CIDR: delegado a python3 (stdlib `ipaddress`), nunca
+# a juicio del agente. Determinístico: mismos rangos existentes -> mismo
+# resultado siempre.
+#
+# ksc_cidr_pick_free <existing_ranges_file>
+#   Busca un rango nuevo recorriendo por DÉCADA (10.<D>.0.0/16 para
+#   sql_private_access, D = 0,10,20,...) y, dentro de cada década, por
+#   offset de subred (10.<D+off>.0.0/22, off = 3,1,2,4..9 — 3 primero
+#   porque es la convención real dominante en este repo: boletera-qa,
+#   cashless-qa/prod usan subred = década+3). pods/svc se derivan del
+#   mismo <D+off> (+102/+106), igual que antes.
+#
+#   Revisión real (Review V1, E-2): la versión anterior probaba un solo
+#   valor de N para los 4 bloques y solo lo validaba contra los rangos
+#   YA EXISTENTES, nunca entre sí — cuando N resultaba múltiplo de 10, la
+#   subred (10.N.0.0/22) quedaba contenida en su propio
+#   sql_private_access (10.N.0.0/16), un solapamiento real que solo se
+#   detecta desplegando. Al forzar off >= 1, la subred nunca cae en la
+#   década exacta de su propio /16 — el solapamiento queda excluido por
+#   construcción, no solo por un chequeo adicional (que también se agrega,
+#   por si la fórmula cambia en el futuro).
+#   Imprime 4 líneas: subred pods svc sql_private_access.
+# ---------------------------------------------------------------------------
+ksc_cidr_pick_free() {
+  local existing_file="$1"
+  python3 - "$existing_file" <<'PYEOF'
+import ipaddress
+import sys
+
+existing_file = sys.argv[1]
+existing = []
+with open(existing_file) as f:
+    for line in f:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            existing.append(ipaddress.ip_network(line, strict=False))
+        except ValueError:
+            continue
+
+def candidate(decada, off):
+    try:
+        subnet = ipaddress.ip_network(f"10.{decada + off}.0.0/22", strict=False)
+        pods = ipaddress.ip_network(f"10.{decada + off + 102}.0.0/17", strict=False)
+        svc = ipaddress.ip_network(f"10.{decada + off + 106}.0.0/23", strict=False)
+        priv = ipaddress.ip_network(f"10.{decada}.0.0/16", strict=False)
+    except ValueError:
+        return None
+    return subnet, pods, svc, priv
+
+def collides(nets, pool):
+    for a in nets:
+        for b in pool:
+            if a.overlaps(b):
+                return True
+    for i, a in enumerate(nets):
+        for b in nets[i + 1:]:
+            if a.overlaps(b):
+                return True
+    return False
+
+# Orden de búsqueda de décadas (Review V2, N-7): preferir la primera
+# década libre POR ENCIMA de la mayor ya usada, y nunca usar la década 0
+# (10.0.x.x se reserva convencionalmente para VPN/defaults/on-prem) salvo
+# que ya no quede ninguna otra libre.
+#
+# Tope real de 140 (Review V3, P-4): svc = 10.<decada+off+106>.0.0/23
+# exige decada+off <= 149 para que el segundo octeto no pase de 255; con
+# el off mínimo (1), eso limita la década máxima usable a 140 — cualquier
+# década >= 150 siempre da `candidate() == None` sin importar el off, así
+# que ni vale la pena generarla. (Una versión anterior de este comentario
+# decía "el siguiente lógico es 150" — eso es matemáticamente imposible
+# con esta fórmula; corregido para no inducir a buscar un comportamiento
+# que no existe.)
+existing_decades = set()
+for net in existing:
+    # Solo /16 cuentan como "década" de sql_private_access.
+    if net.prefixlen == 16:
+        existing_decades.add(int(str(net).split(".")[1]))
+max_decada = max(existing_decades) if existing_decades else 0
+MAX_USABLE_DECADA = 140
+decada_order = list(range(max_decada + 10, MAX_USABLE_DECADA + 1, 10))
+decada_order += [d for d in range(10, MAX_USABLE_DECADA + 1, 10) if d not in decada_order]
+decada_order += [0]  # última opción, nunca primera
+
+for decada in decada_order:
+    for off in (3, 1, 2, 4, 5, 6, 7, 8, 9):
+        cand = candidate(decada, off)
+        if cand is None:
+            continue
+        if not collides(cand, existing):
+            subnet, pods, svc, priv = cand
+            print(subnet)
+            print(pods)
+            print(svc)
+            print(priv)
+            sys.exit(0)
+
+print("NO_FREE_RANGE_FOUND", file=sys.stderr)
+sys.exit(1)
+PYEOF
+}
+
+# ksc_cidr_validate <cidr...> -> exit 0 si todos son válidos, exit 1 si no.
+ksc_cidr_validate() {
+  python3 -c "
+import ipaddress, sys
+for c in sys.argv[1:]:
+    ipaddress.ip_network(c, strict=False)
+" "$@"
+}
+
+# ---------------------------------------------------------------------------
+# Archivo de configuración: campos todavía marcados __PENDIENTE__.
+# ---------------------------------------------------------------------------
+ksc_config_pending_fields() {
+  local file="$1"
+  grep -E '^[A-Z_]+="__PENDIENTE__"' "$file" | sed -E 's/^([A-Z_]+)=.*/\1/'
+}
+
+ksc_config_path() {
+  local repo_root="$1" new_env="$2"
+  printf '%s/.kcreate-scaffolding/%s.config\n' "$repo_root" "$new_env"
+}
+
+ksc_cidr_file_path() {
+  local repo_root="$1" new_env="$2"
+  printf '%s/.kcreate-scaffolding/%s.cidr\n' "$repo_root" "$new_env"
+}
+
+ksc_warnings_file_path() {
+  local repo_root="$1" new_env="$2"
+  printf '%s/.kcreate-scaffolding/%s.warnings\n' "$repo_root" "$new_env"
+}
+
+# Archivo de warnings SOLO de la Construcción (10_build_components.sh),
+# separado del de 02_print_config.sh (doctor). Review V3 (P-3): cuando
+# ambos compartían un único archivo en modo *append*, cada reintento de
+# `10` repetía sus propios WARN sobre los de la corrida anterior (8 ->
+# 14 líneas con un solo retry) — ruido que crece sin límite con cada
+# reintento. Separar los archivos permite que `10` trunque el SUYO en
+# cada corrida (sin repetir sus propios WARN) sin tocar los del doctor
+# (que sí deben sobrevivir intactos entre 02 y 10).
+ksc_build_warnings_file_path() {
+  local repo_root="$1" new_env="$2"
+  printf '%s/.kcreate-scaffolding/%s.build-warnings\n' "$repo_root" "$new_env"
+}
+
+# ---------------------------------------------------------------------------
+# Reemplaza la N-ésima coincidencia (1-indexada) de un regex con un grupo de
+# captura en un archivo, sobre todo el contenido (no línea por línea) — para
+# los casos donde la misma clave aparece varias veces en el mismo archivo
+# (ip_cidr_range, principal_set_suffix) y hay que ubicar exactamente cuál.
+#
+# ksc_replace_nth <file> <regex_con_1_grupo_de_captura> <index> <valor_nuevo>
+# ---------------------------------------------------------------------------
+ksc_replace_nth() {
+  local file="$1" pattern="$2" index="$3" new_value="$4"
+  python3 - "$file" "$pattern" "$index" "$new_value" <<'PYEOF'
+import re, sys
+file, pattern, index, new_value = sys.argv[1], sys.argv[2], int(sys.argv[3]), sys.argv[4]
+with open(file) as f:
+    text = f.read()
+matches = list(re.finditer(pattern, text))
+if len(matches) < index:
+    print(f"ksc_replace_nth: solo hay {len(matches)} coincidencias de "
+          f"'{pattern}' en {file}, se pidió la #{index}", file=sys.stderr)
+    sys.exit(1)
+m = matches[index - 1]
+start, end = m.span(1)
+text = text[:start] + new_value + text[end:]
+with open(file, "w") as f:
+    f.write(text)
+PYEOF
+}
+
+# ksc_set_authorized_networks <file> <"name1=addr1;name2=addr2;...">
+# Reemplaza el bloque authorized_networks completo de sql_postgres. Se
+# reconstruye entero (no se edita a mano) para que nunca quede una coma mal
+# puesta por una edición parcial.
+ksc_set_authorized_networks() {
+  local file="$1" entries_str="$2"
+  python3 - "$file" "$entries_str" <<'PYEOF'
+import re, sys
+file, entries_str = sys.argv[1], sys.argv[2]
+entries = []
+for pair in entries_str.split(";"):
+    if not pair:
+        continue
+    name, addr = pair.split("=", 1)
+    entries.append((name, addr))
+if not entries:
+    print("ksc_set_authorized_networks: lista de entradas vacia", file=sys.stderr)
+    sys.exit(1)
+lines = ["  authorized_networks = ["]
+for name, addr in entries:
+    lines.append(f'    {{ name = "{name}", address = "{addr}" }},')
+lines.append("  ]")
+block = "\n".join(lines)
+with open(file) as f:
+    text = f.read()
+new_text, n = re.subn(r"authorized_networks\s*=\s*\[.*?\]", block, text, count=1, flags=re.DOTALL)
+if n != 1:
+    print(f"ksc_set_authorized_networks: no se encontro el bloque en {file}", file=sys.stderr)
+    sys.exit(1)
+with open(file, "w") as f:
+    f.write(new_text)
+PYEOF
+}
+
+# ksc_set_workload_identity_bindings <file> <terraform_suffix> <repo1;repo2;...>
+# Reconstruye el bloque workload_identity_user_bindings completo: un
+# binding fijo para terraform (preserva el suffix que ya tenía SOURCE_ENV,
+# normalmente "infra-cloud") + un binding github-manager por cada repo en
+# la lista (separada por ";" — soporta apps con más de un repo, Review V1
+# mejora #6). Reemplaza el enfoque anterior de editar por POSICIÓN
+# (ksc_replace_nth sobre la 2.ª coincidencia), que Review V1 señaló como
+# frágil (E-5/mejora #8: si el orden de los bindings en SOURCE_ENV fuera
+# distinto, se habría corrompido el binding de infra-cloud en vez del de
+# la app). Aquí el binding de terraform se identifica por contenido
+# (service_account_email que empieza con "terraform@"), no por posición.
+# `principal_repository_segment` siempre queda como la referencia
+# `local.github_organization` (no un literal) — no hace falta conocer el
+# valor real para reescribir el bloque.
+ksc_set_workload_identity_bindings() {
+  local file="$1" terraform_suffix="$2" repos_str="$3"
+  python3 - "$file" "$terraform_suffix" "$repos_str" <<'PYEOF'
+import re, sys
+file, terraform_suffix, repos_str = sys.argv[1], sys.argv[2], sys.argv[3]
+repos = [r for r in repos_str.split(";") if r]
+if not repos:
+    print("ksc_set_workload_identity_bindings: lista de repos vacia", file=sys.stderr)
+    sys.exit(1)
+
+with open(file) as f:
+    text = f.read()
+
+# No todos los entornos reales tienen un binding de terraform aqui (ej.
+# cashless-qa real solo tiene el de github-manager) — en vez de fallar,
+# se usa un patron por defecto. El binding de terraform->infra-cloud es
+# el que la guia (SS3.15) pide siempre, independientemente de lo que
+# SOURCE_ENV ya tuviera.
+m = re.search(r'service_account_email\s*=\s*"(terraform@[^"]*)"', text)
+if m:
+    terraform_sa = m.group(1)
+else:
+    m2 = re.search(r'service_account_email\s*=\s*"(?:github-manager|terraform)@([^"]*)"', text)
+    project_suffix = m2.group(1) if m2 else "REEMPLAZAR.iam.gserviceaccount.com"
+    terraform_sa = f"terraform@{project_suffix}"
+    print(f"ksc_set_workload_identity_bindings: {file} no tenia un binding de terraform@... (SOURCE_ENV no lo incluia) -- se agrego uno nuevo con suffix 'infra-cloud'", file=sys.stderr)
+github_manager_sa = terraform_sa.replace("terraform@", "github-manager@", 1)
+
+lines = ["  workload_identity_user_bindings = ["]
+lines.append("    {")
+lines.append(f'      service_account_email        = "{terraform_sa}"')
+lines.append("      principal_repository_segment = local.github_organization")
+lines.append(f'      principal_set_suffix         = "{terraform_suffix}"')
+lines.append("    },")
+for i, repo in enumerate(repos):
+    lines.append("    {")
+    lines.append(f'      service_account_email        = "{github_manager_sa}"')
+    lines.append("      principal_repository_segment = local.github_organization")
+    lines.append(f'      principal_set_suffix         = "{repo}"')
+    lines.append("    }" + ("," if i < len(repos) - 1 else ""))
+lines.append("  ]")
+block = "\n".join(lines)
+
+new_text, n = re.subn(
+    r"[ \t]*workload_identity_user_bindings\s*=\s*\[.*?\n\s*\]",
+    block, text, count=1, flags=re.DOTALL,
+)
+if n != 1:
+    print(f"ksc_set_workload_identity_bindings: no encontre el bloque workload_identity_user_bindings en {file}", file=sys.stderr)
+    sys.exit(1)
+with open(file, "w") as f:
+    f.write(new_text)
+PYEOF
+}
+
+# ---------------------------------------------------------------------------
+# "Doctor" de salud de SOURCE_ENV: compara contra TODOS los entornos de
+# live/ (sin hardcodear nombres de API ni de constraint) y emite [WARN]
+# cuando SOURCE_ENV se queda corto respecto a lo que la MAYORÍA de los
+# entornos reales ya tienen. Resuelve Review V1 E-4 (propagación
+# silenciosa de org_policies/project_services incompletos) y el faltante
+# #13 (typo de IP de cloudadmin) con un solo mecanismo genérico: "¿qué
+# hace la mayoría?", no una lista fija de qué debería tener cada archivo.
+# No bloquea nada — solo advierte, porque SOURCE_ENV minimalista a propósito
+# es una posibilidad legítima que el humano puede confirmar.
+# ---------------------------------------------------------------------------
+ksc_check_source_health() {
+  local repo_root="$1" source_env="$2"
+  local envs=() e
+  mapfile -t envs < <(ksc_real_envs "$repo_root")
+  local total="${#envs[@]}"
+  [[ "$total" -le 1 ]] && return 0
+
+  # Entorno de referencia para project_services/org_policies: el que se
+  # modificó más recientemente (git log), no "la mayoría". Un requisito
+  # nuevo de la organización (ej. orgpolicy.googleapis.com, forzado desde
+  # 2026-02-17) por definición todavía NO lo tiene la mayoría de entornos
+  # viejos — una votación por mayoría nunca lo detectaría. El entorno más
+  # reciente es la mejor aproximación disponible, sin tener que hardcodear
+  # el nombre de ninguna API o constraint. Encontrado real probando esto
+  # contra infra-cloud: con mayoría, el hueco real de boletera-qa (falta
+  # orgpolicy.googleapis.com, que solo tiene 1 de 5 entornos) no se
+  # detectaba — con "más reciente" sí.
+  local newest_env="" newest_ts=0 ts
+  for e in "${envs[@]}"; do
+    ts="$(cd "$repo_root" && git log -1 --format=%ct -- "live/$e/project_services/terragrunt.hcl" 2>/dev/null)"
+    [[ -n "$ts" && "$ts" -gt "$newest_ts" ]] && { newest_ts="$ts"; newest_env="$e"; }
+  done
+
+  if [[ -n "$newest_env" && "$newest_env" != "$source_env" \
+        && -f "$repo_root/live/$source_env/project_services/terragrunt.hcl" \
+        && -f "$repo_root/live/$newest_env/project_services/terragrunt.hcl" ]]; then
+    local ref_apis source_apis api
+    ref_apis="$(grep -oE '"[a-zA-Z0-9.-]+\.googleapis\.com"' "$repo_root/live/$newest_env/project_services/terragrunt.hcl" | tr -d '"')"
+    source_apis="$(grep -oE '"[a-zA-Z0-9.-]+\.googleapis\.com"' "$repo_root/live/$source_env/project_services/terragrunt.hcl" | tr -d '"')"
+    while IFS= read -r api; do
+      [[ -n "$api" ]] || continue
+      grep -qx "$api" <<<"$source_apis" || \
+        ksc_warn "doctor: '$api' está habilitada en $newest_env (el entorno modificado más recientemente de live/), pero NO en $source_env — project_services de NEW_ENV va a heredar esta falta en silencio."
+    done <<<"$ref_apis"
+  fi
+
+  if [[ -n "$newest_env" && "$newest_env" != "$source_env" \
+        && -f "$repo_root/live/$source_env/org_policies/terragrunt.hcl" \
+        && -f "$repo_root/live/$newest_env/org_policies/terragrunt.hcl" ]]; then
+    local ref_count source_count
+    ref_count="$(grep -c 'constraint[[:space:]]*=' "$repo_root/live/$newest_env/org_policies/terragrunt.hcl")"
+    source_count="$(grep -c 'constraint[[:space:]]*=' "$repo_root/live/$source_env/org_policies/terragrunt.hcl")"
+    if [[ "$source_count" -lt "$ref_count" ]]; then
+      ksc_warn "doctor: org_policies de $source_env tiene $source_count entradas; $newest_env (el más reciente de live/) tiene $ref_count — NEW_ENV va a heredar un org_policies incompleto."
+    fi
+  fi
+
+  # cloudadmin (u otra IP fija no "dev-*"): aquí SÍ conviene la mayoría en
+  # vez del más reciente — una IP de oficina compartida rara vez cambia
+  # legítimamente, así que el valor mayoritario es el de confianza, no el
+  # del entorno más nuevo (que podría tener el typo).
+  if [[ -f "$repo_root/live/$source_env/sql_postgres/terragrunt.hcl" ]]; then
+    local best best_n _total_unused
+    read -r best best_n _total_unused < <(ksc_majority_fixed_network "$repo_root")
+    if [[ -n "$best" ]]; then
+      local best_name="${best%%=*}"
+      if ! grep -q "name = \"${best_name}\", address = \"${best#*=}\"" "$repo_root/live/$source_env/sql_postgres/terragrunt.hcl" 2>/dev/null; then
+        ksc_warn "doctor: la IP fija '$best' aparece en $best_n/$total entornos de live/, pero $source_env tiene un valor distinto para '$best_name' — verifica si es un typo (ver lessons-learned.md A4). El config de 01_init_config.sh ya adopta el valor mayoritario en vez del de $source_env (ver C-N6) — esto solo avisa, por si el valor de $source_env fuera el correcto a propósito."
+      fi
+    fi
+  fi
+  return 0
+}
+
+# ksc_majority_fixed_network <repo_root> -> imprime "name=addr n total"
+# (la entrada fija más común de sql_postgres.authorized_networks entre
+# todos los entornos reales de live/, excluyendo "dev-*"; en cuántos
+# entornos aparece; y el total de entornos reales considerados). "name"
+# y "addr" vienen vacíos si no hay ninguno. Compartida entre el doctor
+# (ksc_check_source_health) y 01_init_config.sh (que la usa para preferir
+# el valor mayoritario sobre el de SOURCE_ENV cuando difieren — Review
+# V2, N-6: antes el doctor avisaba del typo pero el config igual
+# adoptaba el valor roto de SOURCE_ENV).
+ksc_majority_fixed_network() {
+  local repo_root="$1"
+  local envs=() e
+  mapfile -t envs < <(ksc_real_envs "$repo_root")
+  declare -A ip_count
+  for e in "${envs[@]}"; do
+    local f="$repo_root/live/$e/sql_postgres/terragrunt.hcl" line name addr
+    [[ -f "$f" ]] || continue
+    while IFS= read -r line; do
+      name="$(printf '%s' "$line" | grep -oE 'name[[:space:]]*=[[:space:]]*"[^"]*"' | sed -E 's/.*"([^"]*)"/\1/')"
+      [[ "$name" == dev-* ]] && continue
+      addr="$(printf '%s' "$line" | grep -oE 'address[[:space:]]*=[[:space:]]*"[^"]*"' | sed -E 's/.*"([^"]*)"/\1/')"
+      [[ -n "$name" && -n "$addr" ]] && ip_count["$name=$addr"]=$(( ${ip_count["$name=$addr"]:-0} + 1 ))
+    done < <(grep -E '\{[[:space:]]*name[[:space:]]*=' "$f")
+  done
+  local best="" best_n=0 key n
+  for key in "${!ip_count[@]}"; do
+    n="${ip_count[$key]}"
+    if [[ "$n" -gt "$best_n" ]]; then
+      best="$key"
+      best_n="$n"
+    fi
+  done
+  printf '%s %s %s\n' "$best" "$best_n" "${#envs[@]}"
+}
+
+# ksc_check_duplicate_keys <file> -> exit 1 y lista las claves repetidas
+# DENTRO DE UN MISMO BLOQUE `{ ... }` (no solo mismo nivel de indentación
+# — `locals { project_id = ... }` e `inputs { project_id = ... }` tienen
+# la misma indentación pero son bloques distintos y NO cuentan como
+# duplicado; esto se corrigió tras una primera versión que sí los
+# confundía). Detecta defectos reales de SOURCE_ENV que `terragrunt hcl
+# fmt`/`validate` no atrapan (ej. boletera-qa/sql_postgres trae
+# `update_timeout` dos veces dentro del mismo bloque `inputs`).
+ksc_check_duplicate_keys() {
+  local file="$1"
+  python3 - "$file" <<'PYEOF'
+import re, sys
+file = sys.argv[1]
+with open(file) as f:
+    text = f.read()
+
+stack = [set()]
+dupes = []
+i = 0
+key_re = re.compile(r'[a-zA-Z_][a-zA-Z0-9_]*')
+line_start = True
+pending_key = None
+n = len(text)
+while i < n:
+    c = text[i]
+    if c == '{':
+        stack.append(set())
+        i += 1
+        continue
+    if c == '}':
+        if len(stack) > 1:
+            stack.pop()
+        i += 1
+        continue
+    if c == '\n':
+        line_start = True
+        i += 1
+        continue
+    if line_start and not c.isspace():
+        m = key_re.match(text, i)
+        if m:
+            rest = text[m.end():].lstrip(' \t')
+            if rest.startswith('=') and not rest.startswith('=='):
+                key = m.group(0)
+                if key in stack[-1]:
+                    dupes.append(key)
+                stack[-1].add(key)
+        line_start = False
+    elif not c.isspace():
+        line_start = False
+    i += 1
+
+if dupes:
+    print(f"{file}: clave(s) duplicada(s) dentro del mismo bloque: {', '.join(sorted(set(dupes)))}", file=sys.stderr)
+    sys.exit(1)
+sys.exit(0)
+PYEOF
+}
+
+# ksc_learn_artifact_registry_template <repo_root> -> imprime 2 líneas:
+# la plantilla de repository_id y de description, con el nombre de la
+# app de ESE entorno reemplazado por el marcador {{APP}}/{{APP_CAP}}.
+# Vacío si ningún entorno real de live/ tiene un artifact_registry
+# específico de su propia app (todos genéricos).
+#
+# Review V2 (sección 2.3/4.3): cuando SOURCE_ENV tiene valores genéricos
+# (4 de 5 entornos reales), en vez de solo advertir se intenta "aprender"
+# el patrón real de OTRO entorno que sí lo tenga específico (ej.
+# xoloshop-qa: "club-tijuana-xoloshop-docker-repo") y aplicarlo con el
+# nombre de la app nueva — sin hardcodear "club-tijuana" ni ningún otro
+# literal de esta organización en el código del skill.
+#
+# Review V3 (P-1): la primera versión iteraba `live/*/` directamente, sin
+# pasar por `ksc_real_envs` — exactamente la contaminación que D1/D2 ya
+# habían corregido en las otras tres funciones, pero esta es nueva y se
+# quedó fuera. Reproducido: un entorno sin comitear con
+# `repository_id` conteniendo su propio nombre se "aprendía" como si
+# fuera una plantilla real. Ahora usa `ksc_real_envs` (solo entornos
+# comiteados) y, entre los que matcheen, prefiere el modificado más
+# recientemente (git log) en vez del primero alfabético — mismo criterio
+# que el doctor, para que "cuál entorno es la referencia" no dependa de
+# en qué orden los liste el filesystem.
+ksc_learn_artifact_registry_template() {
+  local repo_root="$1" real_envs=() env_name app id desc best_env="" best_ts=0 ts
+  mapfile -t real_envs < <(ksc_real_envs "$repo_root")
+  for env_name in "${real_envs[@]}"; do
+    [[ -f "$repo_root/live/$env_name/artifact_registry/terragrunt.hcl" ]] || continue
+    app="${env_name%-*}"
+    id="$(ksc_hcl_get "$repo_root/live/$env_name/artifact_registry/terragrunt.hcl" repository_id)"
+    [[ -n "$id" ]] || continue
+    grep -q "$app" <<<"$id" || continue
+    ts="$(cd "$repo_root" && git log -1 --format=%ct -- "live/$env_name/artifact_registry/terragrunt.hcl" 2>/dev/null)"
+    [[ -z "$ts" ]] && ts=0
+    if [[ "$ts" -gt "$best_ts" ]]; then
+      best_ts="$ts"
+      best_env="$env_name"
+    fi
+  done
+  if [[ -n "$best_env" ]]; then
+    app="${best_env%-*}"
+    id="$(ksc_hcl_get "$repo_root/live/$best_env/artifact_registry/terragrunt.hcl" repository_id)"
+    desc="$(ksc_hcl_get "$repo_root/live/$best_env/artifact_registry/terragrunt.hcl" description)"
+    if [[ -n "$id" ]]; then
+      local app_cap
+      app_cap="$(ksc_capitalize "$app")"
+      id="${id//$app/\{\{APP\}\}}"
+      desc="${desc//$app_cap/\{\{APP_CAP\}\}}"
+      desc="${desc//$app/\{\{APP\}\}}"
+      printf '%s\n%s\n' "$id" "$desc"
+      return 0
+    fi
+  fi
+  printf '\n\n'
+  return 1
+}
+
+# Capitaliza solo la primera letra (para "boletera" -> "Boletera").
+ksc_capitalize() {
+  local s="$1"
+  printf '%s%s\n' "$(printf '%s' "${s:0:1}" | tr '[:lower:]' '[:upper:]')" "${s:1}"
+}
+
+# ksc_set_key <file> <clave> <valor_nuevo>
+# Reemplaza el valor de una asignación `clave = "..."` de una sola línea,
+# anclada al nombre exacto de la clave (no toca "project_id" al pedir
+# "project", por ejemplo). Única forma en que este skill edita HCL — nunca
+# con un editor de texto "a mano", siempre con esta función.
+ksc_set_key() {
+  local file="$1" key="$2" value="$3"
+  local escaped_value
+  escaped_value="$(printf '%s' "$value" | sed -e 's/[&]/\\&/g')"
+  sed -i -E "s|^([[:space:]]*${key}[[:space:]]*=[[:space:]]*\")[^\"]*(\")|\1${escaped_value}\2|" "$file"
+}
+
+# Reemplazo literal (no-regex) de SOURCE_ENV/APP por NEW_ENV/APP en todo el
+# archivo. Cubre la mayoría de los campos específicos del entorno, porque la
+# convención de este repo embebe el nombre completo del entorno
+# (<app>-<qa|prod>) literalmente en nombres de red, SA, cluster, buckets.
+ksc_substr_replace() {
+  local file="$1" old="$2" new="$3"
+  sed -i "s/${old}/${new}/g" "$file"
+}
+
+# ksc_substr_replace_app <file> <app_source_lower> <app_new_lower>
+#
+# Reemplaza TODAS las variantes de capitalización del nombre corto de la
+# app fuente (no solo minúscula exacta ni "Primera-mayúscula" exacta) por
+# la variante equivalente del nombre nuevo. Caso real encontrado
+# construyendo `coreservices-qa` desde `xoloshop-qa`: `service_accounts`
+# usa el nombre de marca estilizado `"XoloShop"` (con S interna
+# mayúscula) en `display_name`/`description` — ni
+# `ksc_substr_replace "$APP_SOURCE"` (minúscula exacta) ni
+# `ksc_substr_replace "$(ksc_capitalize "$APP_SOURCE")"` ("Xoloshop",
+# solo la primera letra) hacen match contra "XoloShop", así que ese
+# leftover pasaba completo a `coreservices-qa` en silencio. Resuelto
+# haciendo el match insensible a mayúsculas/minúsculas y eligiendo la
+# capitalización del REEMPLAZO según cómo estaba escrita la coincidencia
+# encontrada (todo minúsculas -> nuevo en minúsculas; todo mayúsculas ->
+# nuevo en mayúsculas; cualquier otra mezcla, incluidos estilos de marca
+# como "XoloShop" -> primera letra mayúscula del nuevo, mejor esfuerzo).
+ksc_substr_replace_app() {
+  local file="$1" app_source="$2" app_new="$3"
+  [[ -f "$file" ]] || return 0
+  python3 - "$file" "$app_source" "$app_new" <<'PYEOF'
+import re, sys
+file, app_source, app_new = sys.argv[1], sys.argv[2], sys.argv[3]
+with open(file) as f:
+    text = f.read()
+pattern = re.compile(re.escape(app_source), re.IGNORECASE)
+
+def repl(m):
+    s = m.group(0)
+    if s.isupper() and len(s) > 1:
+        return app_new.upper()
+    if s.islower():
+        return app_new.lower()
+    return app_new[:1].upper() + app_new[1:].lower()
+
+new_text = pattern.sub(repl, text)
+with open(file, "w") as f:
+    f.write(new_text)
+PYEOF
+}