YAML to ENV converter

Variáveis de ambiente são um dos pilares do desenvolvimento de software moderno — a The Twelve-Factor App (12factor.net), o manifesto de boas práticas para aplicações cloud-native publicado pelo time do Heroku, dedica um capítulo inteiro ao princípio de separar configuração do código-fonte. A ideia é simples: tudo que muda entre ambientes (dev, staging, produção) — strings de conexão com banco, chaves de API, flags de feature — deve ser injetado via variáveis de ambiente, nunca hardcoded no código. Isso permite um único artefato de build que funciona em qualquer ambiente só com variáveis diferentes. O arquivo `.env` nasceu dessa prática: um arquivo de texto simples com pares KEY=VALUE que ferramentas como `dotenv` (Node.js), `python-decouple` (Python) e `vlucas/phpdotenv` (PHP) carregam automaticamente.

YAML se tornou o formato de configuração dominante no mundo DevOps e cloud. Kubernetes armazena toda sua configuração em YAML — Deployments, Services, ConfigMaps, Secrets. Docker Compose usa YAML. Helm Charts usam YAML. GitHub Actions usa YAML. O problema surge quando você precisa rodar localmente algo que em produção é configurado via YAML num ConfigMap do Kubernetes ou num arquivo de configuração de serviço: você precisa extrair as variáveis desse YAML e transformá-las em um `.env` que o seu ambiente de dev entenda. Fazer isso manualmente — abrir o YAML, ir campo a campo, converter a hierarquia `database.host: localhost` em `DATABASE_HOST=localhost` — é tedioso e propenso a erros.

A conversão de YAML hierárquico para o formato flat KEY=VALUE do `.env` exige uma regra de achatamento: a hierarquia `database.host` vira a chave `DATABASE_HOST` (letras maiúsculas, pontos substituídos por underscores). Chaves com arrays são mais complicadas — arrays em YAML não têm um equivalente direto em variáveis de ambiente, e a convenção varia: alguns usam `SERVICE_HOSTS_0`, `SERVICE_HOSTS_1`; outros preferem serializar o array como JSON na variável. Esta ferramenta adota uma abordagem conservadora e prática, gerando chaves planas para valores escalares, que cobrem a grande maioria dos casos de uso.

Uma nota sobre segurança e boas práticas: o arquivo `.env` nunca deve ser commitado no repositório. O `.gitignore` do projeto deve sempre incluir `.env` e qualquer variante como `.env.local` e `.env.production`. O que pode (e deve) ser versionado é um arquivo `.env.example` com as chaves mas sem os valores reais, servindo como documentação do que o projeto precisa para funcionar. Para ambientes com muitos segredos, considere um gerenciador de segredos como AWS Secrets Manager, HashiCorp Vault ou Doppler, que injetam as variáveis no runtime sem que elas precisem tocar o disco.

Environment variables are one of the pillars of modern software development — The Twelve-Factor App (12factor.net), the cloud-native best practices manifesto published by the Heroku team, dedicates an entire section to separating configuration from source code. The idea is simple: everything that changes between environments (dev, staging, production) — database connection strings, API keys, feature flags — should be injected via environment variables, never hardcoded. This allows a single build artifact to work in any environment with only different variables. The `.env` file was born from this practice: a plain-text file with KEY=VALUE pairs that tools like `dotenv` (Node.js), `python-decouple` (Python), and `vlucas/phpdotenv` (PHP) load automatically.

YAML has become the dominant configuration format in the DevOps and cloud world. Kubernetes stores all its configuration in YAML — Deployments, Services, ConfigMaps, Secrets. Docker Compose uses YAML. Helm Charts use YAML. GitHub Actions uses YAML. The problem arises when you need to run locally something that in production is configured via YAML in a Kubernetes ConfigMap or service config file: you need to extract the variables from that YAML and transform them into a `.env` your dev environment understands. Doing this manually — opening the YAML, going field by field, converting `database.host: localhost` to `DATABASE_HOST=localhost` — is tedious and error-prone.

Converting hierarchical YAML to the flat KEY=VALUE format of `.env` requires a flattening rule: the hierarchy `database.host` becomes `DATABASE_HOST` (uppercase letters, dots replaced by underscores). Keys with arrays are trickier — YAML arrays have no direct equivalent in environment variables, and convention varies: some use `SERVICE_HOSTS_0`, `SERVICE_HOSTS_1`; others prefer serializing the array as JSON in the variable. This tool takes a conservative, practical approach, generating flat keys for scalar values, which covers the vast majority of use cases.

A security and best practices note: the `.env` file should never be committed to the repository. Your `.gitignore` should always include `.env` and any variants like `.env.local` and `.env.production`. What can (and should) be versioned is an `.env.example` file with the keys but without real values, serving as documentation of what the project needs to run. For environments with many secrets, consider a secrets manager like AWS Secrets Manager, HashiCorp Vault, or Doppler, which inject variables at runtime without them ever touching disk.

Las variables de entorno son uno de los pilares del desarrollo de software moderno — The Twelve-Factor App (12factor.net), el manifiesto de buenas prácticas para aplicaciones cloud-native publicado por el equipo de Heroku, dedica una sección completa al principio de separar la configuración del código fuente. La idea es simple: todo lo que cambia entre entornos (dev, staging, producción) — cadenas de conexión a base de datos, claves de API, feature flags — debe inyectarse mediante variables de entorno, nunca hardcodeado. Esto permite un único artefacto de build que funciona en cualquier entorno con solo cambiar las variables. El archivo `.env` nació de esta práctica: un archivo de texto simple con pares KEY=VALUE que herramientas como `dotenv` (Node.js), `python-decouple` (Python) y `vlucas/phpdotenv` (PHP) cargan automáticamente.

YAML se ha convertido en el formato de configuración dominante en el mundo DevOps y cloud. Kubernetes almacena toda su configuración en YAML — Deployments, Services, ConfigMaps, Secrets. Docker Compose usa YAML. Helm Charts usan YAML. GitHub Actions usa YAML. El problema surge cuando necesitas ejecutar localmente algo que en producción está configurado mediante YAML en un ConfigMap de Kubernetes o en un archivo de configuración de servicio: tienes que extraer las variables de ese YAML y transformarlas en un `.env` que tu entorno de desarrollo entienda. Hacer esto manualmente — abrir el YAML, ir campo a campo, convertir `database.host: localhost` en `DATABASE_HOST=localhost` — es tedioso y propenso a errores.

Convertir YAML jerárquico al formato plano KEY=VALUE del `.env` requiere una regla de aplanamiento: la jerarquía `database.host` se convierte en `DATABASE_HOST` (mayúsculas, puntos reemplazados por guiones bajos). Las claves con arrays son más complicadas — los arrays en YAML no tienen un equivalente directo en variables de entorno, y la convención varía: algunos usan `SERVICE_HOSTS_0`, `SERVICE_HOSTS_1`; otros prefieren serializar el array como JSON en la variable. Esta herramienta adopta un enfoque conservador y práctico, generando claves planas para valores escalares, que cubre la gran mayoría de los casos de uso.

Una nota sobre seguridad y buenas prácticas: el archivo `.env` nunca debe commitearse en el repositorio. El `.gitignore` del proyecto debe incluir siempre `.env` y cualquier variante como `.env.local` y `.env.production`. Lo que sí puede (y debe) versionarse es un archivo `.env.example` con las claves pero sin los valores reales, que sirve como documentación de lo que el proyecto necesita para funcionar. Para entornos con muchos secretos, considera un gestor de secretos como AWS Secrets Manager, HashiCorp Vault o Doppler, que inyectan las variables en runtime sin que tengan que tocar el disco.