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: [
        // 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

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. custom_checks
6. cmds

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 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: "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: "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: """
            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: """
            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: """
            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://.*$"
        }]},
    ]
}

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: {
            // 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 - 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