Dependências de Variáveis de Ambiente

Dependências de variáveis de ambiente verificam se variáveis requeridas existem antes que seu comando seja executado. Verificações nos níveis raiz, comando e implementação usam o ambiente do host capturado do usuário. Verificações declaradas dentro da configuração do runtime container selecionado rodam dentro do container.

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: [
        // Either AWS_ACCESS_KEY_ID OR 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: [
        // Must be set AND match semver format
        {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

Dentro de cada fase de validação de dependências, variáveis de ambiente são verificadas primeiro:

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

Para dependências no host, isso valida o ambiente real do usuário antes de aplicar variáveis da construção env do Invowk™. A fase do runtime container usa o ambiente do container selecionado.

Exemplos do Mundo Real

Credenciais AWS

{
    name: "deploy"
    description: "Deploy to AWS"
    depends_on: {
        env_vars: [
            // Need either access key or profile
            {alternatives: [
                {name: "AWS_ACCESS_KEY_ID"},
                {name: "AWS_PROFILE"}
            ]},
            // Region is required
            {alternatives: [{name: "AWS_REGION"}]}
        ]
        tools: [{alternatives: ["aws"]}]
    }
    implementations: [{
        script: {content: "aws s3 sync ./dist s3://my-bucket"}
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Conexão com Banco de Dados

{
    name: "db migrate"
    description: "Run database migrations"
    depends_on: {
        env_vars: [
            {alternatives: [{
                name: "DATABASE_URL"
                // Validate it looks like a connection string
                validation: "^postgres(ql)?://.*$"
            }]}
        ]
        tools: [{alternatives: ["migrate", "goose"]}]
    }
    implementations: [{
        script: {content: "migrate -path ./migrations -database $DATABASE_URL up"}
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Chaves de API

{
    name: "publish"
    description: "Publish package to registry"
    depends_on: {
        env_vars: [
            // NPM token for publishing
            {alternatives: [{name: "NPM_TOKEN"}]},
        ]
        tools: [{alternatives: ["npm"]}]
    }
    implementations: [{
        script: {content: """
            echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
            npm publish
            """}
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Configuração Específica de Ambiente

{
    name: "deploy"
    description: "Deploy to target environment"
    depends_on: {
        env_vars: [
            // DEPLOY_ENV must be one of: dev, staging, prod
            {alternatives: [{
                name: "DEPLOY_ENV"
                validation: "^(dev|staging|prod)$"
            }]}
        ]
    }
    implementations: [{
        script: {content: """
            echo "Deploying to $DEPLOY_ENV..."
            ./scripts/deploy-$DEPLOY_ENV.sh
            """}
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Validação de Versão

{
    name: "release"
    description: "Create a release"
    depends_on: {
        env_vars: [
            // Version must be semantic
            {alternatives: [{
                name: "VERSION"
                validation: "^v?[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9]+)?$"
            }]},
            // Git tag message
            {alternatives: [{name: "RELEASE_NOTES"}]}
        ]
    }
    implementations: [{
        script: {content: """
            git tag -a "$VERSION" -m "$RELEASE_NOTES"
            git push origin "$VERSION"
            """}
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Padrões Comuns de Validação

Versão Semântica

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

URL

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

Tipo Email

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

ID Alfanumérico

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

Região AWS

validation: "^[a-z]{2}-[a-z]+-[0-9]+$"
// Matches: us-east-1, eu-west-2
// Rejects: 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: [
        // Need API_KEY AND API_SECRET AND API_URL
        {alternatives: [{name: "API_KEY"}]},
        {alternatives: [{name: "API_SECRET"}]},
        {alternatives: [{
            name: "API_URL"
            validation: "^https://.*$"
        }]},
    ]
}

Contexto da Verificação

Dependências de ambiente nos níveis raiz, comando e implementação verificam o ambiente do host do usuário, não variáveis definidas pelo Invowk:

{
    name: "example"
    env: {
        vars: {
            // This is set by Invowk during execution
            MY_VAR: "value"
        }
    }
    depends_on: {
        env_vars: [
            // This checks the USER's environment, BEFORE Invowk sets MY_VAR
            // So it will fail if the user hasn't set MY_VAR themselves
            {alternatives: [{name: "MY_VAR"}]}
        ]
    }
}

Isso é intencional: essas verificações validam o que o usuário configurou, não o que o comando vai definir. Uma dependência env_vars dentro da configuração do runtime container selecionado é diferente—ela é verificada dentro do container contra o ambiente de runtime.

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