Dependências de Variáveis de Ambiente

Dependências de variáveis de ambiente verificam se variáveis de ambiente requeridas existem antes que seu comando seja executado. Elas são verificadas primeiro, antes de quaisquer outras dependências, contra o ambiente real do usuário.

Uso Básico

depends_on: {
    env_vars: [
        {alternatives: [{name: "API_KEY"}]},
        {alternatives: [{name: "DATABASE_URL"}, {name: "DB_URL"}]}
    ]
}

Se a variável não estiver definida:

✗ Dependencies not satisfied

Command 'deploy' has unmet dependencies:

Missing Environment Variables:
  • AWS_ACCESS_KEY_ID - not set in environment

Set the required environment variables and try again.

Alternativas (Semântica OU)

Requer uma de múltiplas variáveis:

depends_on: {
    env_vars: [
        // AWS_ACCESS_KEY_ID OU AWS_PROFILE
        {alternatives: [
            {name: "AWS_ACCESS_KEY_ID"},
            {name: "AWS_PROFILE"}
        ]}
    ]
}

A dependência é satisfeita se qualquer alternativa existir.

Validação por Regex

Valide que o valor da variável corresponde a um padrão:

depends_on: {
    env_vars: [
        // Deve estar definido E corresponder ao formato semver
        {alternatives: [{
            name: "VERSION"
            validation: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
        }]}
    ]
}

Se o valor não corresponder:

✗ Dependencies not satisfied

Command 'release' has unmet dependencies:

Invalid Environment Variables:
  • VERSION - value "invalid" does not match pattern "^[0-9]+\.[0-9]+\.[0-9]+$"

Ordem de Validação

Variáveis de ambiente são verificadas primeiro, antes de todas as outras dependências:

1. env_vars ← Verificado primeiro!
2. tools
3. filepaths
4. capabilities
5. commands
6. custom_checks

Isso garante que você está validando contra o ambiente real do usuário, não variáveis definidas pela construção env do Invowk™.

Exemplos do Mundo Real

Credenciais AWS

{
    name: "deploy"
    description: "Deploy para AWS"
    depends_on: {
        env_vars: [
            // Precisa de access key ou profile
            {alternatives: [
                {name: "AWS_ACCESS_KEY_ID"},
                {name: "AWS_PROFILE"}
            ]},
            // Region é obrigatória
            {alternatives: [{name: "AWS_REGION"}]}
        ]
        tools: [{alternatives: ["aws"]}]
    }
    implementations: [{
        script: "aws s3 sync ./dist s3://my-bucket"
        runtimes: [{name: "native"}]
    }]
}

Conexão com Banco de Dados

{
    name: "db migrate"
    description: "Executar migrações do banco de dados"
    depends_on: {
        env_vars: [
            {alternatives: [{
                name: "DATABASE_URL"
                // Validar que parece uma string de conexão
                validation: "^postgres(ql)?://.*$"
            }]}
        ]
        tools: [{alternatives: ["migrate", "goose"]}]
    }
    implementations: [{
        script: "migrate -path ./migrations -database $DATABASE_URL up"
        runtimes: [{name: "native"}]
    }]
}

Chaves de API

{
    name: "publish"
    description: "Publicar pacote no registry"
    depends_on: {
        env_vars: [
            // Token NPM para publicação
            {alternatives: [{name: "NPM_TOKEN"}]},
        ]
        tools: [{alternatives: ["npm"]}]
    }
    implementations: [{
        script: """
            echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
            npm publish
            """
        runtimes: [{name: "native"}]
    }]
}

Configuração Específica de Ambiente

{
    name: "deploy"
    description: "Deploy para ambiente alvo"
    depends_on: {
        env_vars: [
            // DEPLOY_ENV deve ser um de: dev, staging, prod
            {alternatives: [{
                name: "DEPLOY_ENV"
                validation: "^(dev|staging|prod)$"
            }]}
        ]
    }
    implementations: [{
        script: """
            echo "Fazendo deploy para $DEPLOY_ENV..."
            ./scripts/deploy-$DEPLOY_ENV.sh
            """
        runtimes: [{name: "native"}]
    }]
}

Validação de Versão

{
    name: "release"
    description: "Criar um release"
    depends_on: {
        env_vars: [
            // Versão deve ser semântica
            {alternatives: [{
                name: "VERSION"
                validation: "^v?[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9]+)?$"
            }]},
            // Mensagem da tag git
            {alternatives: [{name: "RELEASE_NOTES"}]}
        ]
    }
    implementations: [{
        script: """
            git tag -a "$VERSION" -m "$RELEASE_NOTES"
            git push origin "$VERSION"
            """
        runtimes: [{name: "native"}]
    }]
}

Padrões Comuns de Validação

Versão Semântica

validation: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
// Corresponde: 1.0.0, 2.1.3
// Rejeita: v1.0.0, 1.0, latest

URL

validation: "^https?://[^\\s]+$"
// Corresponde: http://localhost, https://example.com/path
// Rejeita: ftp://server, not-a-url

Tipo Email

validation: "^[^@]+@[^@]+\\.[^@]+$"
// Corresponde: user@example.com
// Rejeita: invalid, @example.com

ID Alfanumérico

validation: "^[a-zA-Z0-9_-]+$"
// Corresponde: my-project_123, ABC
// Rejeita: my project, name@here

Região AWS

validation: "^[a-z]{2}-[a-z]+-[0-9]+$"
// Corresponde: us-east-1, eu-west-2
// Rejeita: US-EAST-1, us_east_1

Múltiplos Requisitos

Combine múltiplas verificações de variáveis de ambiente (lógica E):

depends_on: {
    env_vars: [
        // Precisa de API_KEY E API_SECRET E API_URL
        {alternatives: [{name: "API_KEY"}]},
        {alternatives: [{name: "API_SECRET"}]},
        {alternatives: [{
            name: "API_URL"
            validation: "^https://.*$"
        }]},
    ]
}

Importante: Apenas Ambiente do Usuário

Dependências de variáveis de ambiente verificam o ambiente do usuário, não variáveis definidas pelo Invowk:

{
    name: "example"
    env: {
        vars: {
            // Isso é definido pelo Invowk durante a execução
            MY_VAR: "value"
        }
    }
    depends_on: {
        env_vars: [
            // Isso verifica o ambiente do USUÁRIO, ANTES do Invowk definir MY_VAR
            // Então vai falhar se o usuário não tiver definido MY_VAR ele mesmo
            {alternatives: [{name: "MY_VAR"}]}
        ]
    }
}

Isso é intencional - você está validando o que o usuário configurou, não o que seu comando vai definir.

Melhores Práticas

1. Use alternativas para métodos de auth: {alternatives: [{name: "TOKEN"}, {name: "API_KEY"}]}
2. Adicione validação quando o formato importa: Especialmente para URLs, versões e IDs
3. Documente variáveis requeridas: Usuários precisam saber o que definir
4. Considere gerenciamento de secrets: Não logue valores sensíveis

Próximos Passos

• Custom Checks - Escrever scripts de validação personalizados
• Overview - Retornar à visão geral de dependências