hcl-utils

CLI Python para validar e sintetizar documentos HCL, JSON e YAML.

Instalação

Requer Python 3.10 ou superior.

pip install .

Uso

Validar um arquivo ou diretório HCL (a busca em diretórios é recursiva):

hcl-utils validate --input infra/

Converter uma árvore HCL para YAML, preservando seus caminhos relativos:

hcl-utils synth --input infra/ --output generated/ --output-format yaml

Os formatos de entrada disponíveis em --input-format são hcl (padrão), json e yaml. Os formatos de saída são hcl (padrão), json, yaml e tf; tf usa a serialização HCL com extensão .tf.

Por segurança, destinos existentes causam erro. Use --overwrite para substituir somente os arquivos que seriam gerados nesta execução.

Modelo JSON/YAML canônico

JSON e YAML representam o corpo de um documento HCL como um objeto na raiz. Blocos e expressões usam chaves reservadas:

resource:
  - __is_block__: true
    __labels__: [aws_s3_bucket, logs]
    bucket: logs
    region:
      __expression__: var.region

Strings comuns são literais. Atributos iniciados por __ são reservados e rejeitados, exceto __is_block__, __labels__ e __expression__ com a forma mostrada acima.

Diagnósticos são emitidos em stderr; use --diagnostic-format=json para uma lista JSON apropriada para automação.

Contratos de síntese

Um contrato salva uma receita de síntese reutilizável no projeto. Crie um com caminhos relativos ao diretório do projeto:

hcl-utils contract create gerar-yaml \
  --input assets/hcl \
  --output assets/output \
  --output-format yaml

O comando cria .hcl-utils/contracts/gerar-yaml.yaml. Liste as receitas e execute uma delas de qualquer subdiretório do projeto:

hcl-utils contract list
hcl-utils contract run gerar-yaml

Use --overwrite em contract create ou contract run somente quando quiser substituir explicitamente o arquivo de contrato ou seus destinos de saída.

Schema de entrada

Um contrato pode validar cada documento de entrada antes de executar addons. O schema usa JSON Schema Draft 2020-12 e pode ser JSON, YAML ou HCL:

hcl-utils contract create gerar-json-validado \
  --input assets/hcl \
  --output assets/output \
  --output-format json \
  --schema .hcl-utils/schemas/infra.yaml

Uma violação impede a execução de addons e a escrita de qualquer saída. O diagnóstico indica o arquivo de entrada e o caminho da propriedade inválida.

Addons de contratos

Addons são módulos Python locais executados entre a leitura da entrada e a escrita da saída. Crie um esqueleto e associe-o a uma receita:

hcl-utils addons create adicionar-metadado

hcl-utils contract create gerar-json \
  --input assets/hcl \
  --output assets/output \
  --output-format json \
  --addons adicionar-metadado \
  --addons-mode each

O arquivo fica em .hcl-utils/addons/adicionar-metadado.py e expõe run(data) -> data. No modo each, use data.document; no padrão batch, use data.documents. Em ambos os modos, data.context expõe os dados imutáveis da execução. Addons devem preservar os documentos e seus caminhos, podendo alterar somente document.data.