Pular para o conteúdo principal
Versão: 0.1.0-alpha.2

Visão Geral de Ambiente

O Invowk™ fornece gerenciamento poderoso de variáveis de ambiente para seus comandos. Defina variáveis, carregue de arquivos e controle a precedência em múltiplos níveis.

Exemplo Rápido​

{
    name: "build"
    env: {
        // Load from .env files
        files: [".env", ".env.local?"]  // ? means optional
        
        // Set variables directly
        vars: {
            NODE_ENV: "production"
            BUILD_DATE: "$(date +%Y-%m-%d)"
        }
    }
    implementations: [{
        script: """
            echo "Building for $NODE_ENV"
            echo "Date: $BUILD_DATE"
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Fontes de Ambiente​

Variáveis vêm de múltiplas fontes, em ordem de precedência (mais alta primeiro):

  1. Vars da CLI - --env-var KEY=value
  2. Arquivos env da CLI - --env-file .env.custom
  3. Vars do Invowk - INVOWK_FLAG_* / INVOWK_ARG_*
  4. Vars de implementação - env.vars no nível de implementação
  5. Vars de comando - env.vars no nível de comando
  6. Vars raiz - env.vars no nível raiz
  7. Arquivos de implementação - env.files no nível de implementação
  8. Arquivos de comando - env.files no nível de comando
  9. Arquivos raiz - env.files no nível raiz
  10. Ambiente do sistema - Variáveis do host (sujeito a env_inherit_mode)

Fontes anteriores sobrescrevem as posteriores.

Níveis de Escopo​

Nível Raiz​

Aplica-se a todos os comandos no invkfile:

env: {
    vars: {
        PROJECT_NAME: "myproject"
    }
}

cmds: [...]  // All commands get PROJECT_NAME

Nível de Comando​

Aplica-se a um comando específico:

{
    name: "build"
    env: {
        vars: {
            BUILD_MODE: "release"
        }
    }
    implementations: [...]
}

Nível de Implementação​

Aplica-se a uma implementação específica:

{
    name: "build"
    implementations: [
        {
            script: "npm run build"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
            env: {
                vars: {
                    NODE_ENV: "production"
                }
            }
        }
    ]
}

Nível de Plataforma​

Defina variáveis por plataforma:

// Platform-specific env requires separate implementations
implementations: [
    {
        script: "echo $CONFIG_PATH"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}]
        env: {vars: {CONFIG_PATH: "/etc/myapp/config"}}
    },
    {
        script: "echo $CONFIG_PATH"
        runtimes: [{name: "native"}]
        platforms: [{name: "macos"}]
        env: {vars: {CONFIG_PATH: "/usr/local/etc/myapp/config"}}
    }
]

Arquivos Env​

Carregue variáveis de arquivos .env:

env: {
    files: [
        ".env",           // Required - fails if missing
        ".env.local?",    // Optional - suffix with ?
        ".env.${ENV}?",   // Interpolation - uses ENV variable
    ]
}

Arquivos são carregados em ordem; arquivos posteriores sobrescrevem os anteriores.

Veja Env Files para detalhes.

Variáveis de Ambiente​

Defina variáveis diretamente:

env: {
    vars: {
        API_URL: "https://api.example.com"
        DEBUG: "true"
        VERSION: "1.0.0"
    }
}

Veja Env Vars para detalhes.

Sobrescrita via CLI​

Sobrescreva em tempo de execução:

# Set a single variable
invowk cmd build --invk-env-var NODE_ENV=development

# Set multiple variables
invowk cmd build --invk-env-var NODE_ENV=dev --invk-env-var DEBUG=true

# Load from a file
invowk cmd build --invk-env-file .env.local

# Combine
invowk cmd build --invk-env-file .env.local --invk-env-var OVERRIDE=value

Herança do Ambiente do Host​

Por padrão, os runtimes native e virtual herdam o ambiente do host, enquanto o runtime container começa sem variáveis do host. Você pode controlar isso por runtime ou por execução.

runtimes: [{
    name:              "container"
    image:             "alpine:latest"
    env_inherit_mode:  "allow"
    env_inherit_allow: ["TERM", "LANG"]
    env_inherit_deny:  ["AWS_SECRET_ACCESS_KEY"]
}]
invowk cmd examples hello \
  --invk-env-inherit-mode allow \
  --invk-env-inherit-allow TERM \
  --invk-env-inherit-allow LANG \
  --invk-env-inherit-deny AWS_SECRET_ACCESS_KEY

Variáveis Embutidas​

O Invowk fornece variáveis para flags e argumentos:

  • INVOWK_FLAG_* - Valores de flag
  • INVOWK_ARG_* - Valores de argumento

Ambiente de Container​

Para runtime container, o ambiente é passado para dentro do container:

{
    name: "build"
    env: {
        vars: {
            BUILD_ENV: "container"
        }
    }
    implementations: [{
        script: "echo $BUILD_ENV"  // Available inside container
        runtimes: [{name: "container", image: "debian:bookworm-slim"}]
        platforms: [{name: "linux"}]
    }]
}

Comandos Aninhados​

Quando um comando invoca outro comando, algumas variáveis são isoladas:

Isoladas (NÃO herdadas):

  • INVOWK_ARG_*
  • INVOWK_FLAG_*

Herdadas (comportamento UNIX normal):

  • Variáveis de env.vars
  • Variáveis de nível de plataforma
  • Ambiente do sistema

Isso impede que argumentos do comando pai vazem para comandos filhos.

Próximos Passos​