Visão Geral de Dependências

Dependências permitem que você declare o que seu comando precisa antes de executar. O Invowk™ valida todas as dependências antecipadamente e fornece mensagens de erro claras quando algo está faltando.

Por Que Declarar Dependências?

Sem verificações de dependência:

$ invowk cmd build
./scripts/build.sh: line 5: go: command not found

Com verificações de dependência:

$ invowk cmd build

✗ Dependencies not satisfied

Command 'build' has unmet dependencies:

Missing Tools:
  • go - not found in PATH

Install the missing tools and try again.

Muito melhor! Você sabe exatamente o que está errado antes de qualquer coisa executar.

Tipos de Dependência

O Invowk suporta seis tipos de dependências:

Tipo	Verifica
tools	Binários no PATH
filepaths	Arquivos ou diretórios
cmds	Outros comandos Invowk
capabilities	Capacidades do sistema
env_vars	Variáveis de ambiente
custom_checks	Scripts de validação personalizados

Sintaxe Básica

Dependências são declaradas no bloco depends_on:

{
    name: "build"
    depends_on: {
        tools: [
            {alternatives: ["go"]}
        ]
        filepaths: [
            {alternatives: ["go.mod"]}
        ]
    }
    implementations: [...]
}

O Padrão de Alternativas

Toda dependência usa uma lista alternatives com semântica OU:

// ANY of these tools satisfies the dependency
tools: [
    {alternatives: ["podman", "docker"]}
]

// ANY of these files satisfies the dependency
filepaths: [
    {alternatives: ["config.yaml", "config.json", "config.toml"]}
]

Se qualquer alternativa for encontrada, a dependência é satisfeita. O Invowk usa retorno antecipado - ele para de verificar assim que uma corresponde.

Ordem de Validação

Dependências são validadas nesta ordem:

1. env_vars - Variáveis de ambiente (verificadas primeiro!)
2. tools - Binários no PATH
3. filepaths - Arquivos e diretórios
4. capabilities - Capacidades do sistema
5. custom_checks - Scripts de validação personalizados
6. cmds - Outros comandos Invowk

Variáveis de ambiente são validadas primeiro, antes do Invowk definir qualquer ambiente no nível do comando. Isso garante que você está verificando o ambiente real do usuário.

Níveis de Escopo

Dependências podem ser declaradas em três níveis:

Nível Raiz (Global)

Aplica-se a todos os comandos no invowkfile:

depends_on: {
    tools: [{alternatives: ["git"]}]  // Required by all commands
}

cmds: [...]

Nível de Comando

Aplica-se a um comando específico:

{
    name: "build"
    depends_on: {
        tools: [{alternatives: ["go"]}]  // Required by this command
    }
    implementations: [...]
}

Nível de Implementação

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

{
    name: "build"
    implementations: [
        {
            script: "go build ./..."
            runtimes: [{name: "container", image: "golang:1.26"}]
            platforms: [{name: "linux"}]
            depends_on: {
                // Validated INSIDE the container
                tools: [{alternatives: ["go"]}]
            }
        }
    ]
}

Herança de Escopo

Dependências são combinadas entre níveis:

// Root level: requires git
depends_on: {
    tools: [{alternatives: ["git"]}]
}

cmds: [
    {
        name: "build"
        // Command level: also requires go
        depends_on: {
            tools: [{alternatives: ["go"]}]
        }
        implementations: [
            {
                script: "go build ./..."
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}]
                // Implementation level: also requires make
                depends_on: {
                    tools: [{alternatives: ["make"]}]
                }
            }
        ]
    }
]

// Effective dependencies for "build": git + go + make

Validação Consciente do Runtime

Dependências declaradas no nível raiz, comando ou implementação são sempre validadas no sistema host, independentemente do runtime selecionado. Isso garante que pré-requisitos do host (como um engine de container) sejam verificados antes do início da execução.

Para validar dependências dentro do ambiente do container, use depends_on dentro de um bloco de runtime container:

{
    name: "build"
    implementations: [
        {
            script: "go build ./..."
            runtimes: [{
                name: "container"
                image: "golang:1.26"
                depends_on: {
                    // Checked INSIDE the container
                    tools: [{alternatives: ["go"]}]
                    filepaths: [{alternatives: ["/workspace/go.mod"]}]
                }
            }]
            platforms: [{name: "linux"}]
            // Host-level: always checked on the host
            depends_on: {
                tools: [{alternatives: ["docker", "podman"]}]
            }
        }
    ]
}

Dependências do Runtime Container

O bloco depends_on dentro da configuração de um runtime container valida contra o ambiente do container. Isso está disponível apenas para o runtime container — os runtimes native e virtual não suportam depends_on no nível de runtime.

Escopo	Validado Contra
depends_on de Raiz / Comando / Implementação	Sempre o sistema host
depends_on do runtime container	O ambiente do container

Essa separação permite expressar requisitos tanto do host quanto do container:

{
    name: "deploy"
    implementations: [{
        script: "./scripts/deploy.sh"
        runtimes: [{
            name: "container"
            image: "debian:stable-slim"
            depends_on: {
                // These are validated inside the container
                tools: [{alternatives: ["kubectl"]}]
                env_vars: [{alternatives: [{name: "KUBECONFIG"}]}]
            }
        }]
        platforms: [{name: "linux"}]
        // These are validated on the host (regardless of runtime)
        depends_on: {
            tools: [{alternatives: ["docker", "podman"]}]
            env_vars: [{alternatives: [{name: "DOCKER_HOST"}]}]
        }
    }]
}

Apenas o depends_on do runtime selecionado é validado. Se um comando tem múltiplos runtimes listados, as deps dos runtimes não selecionados são ignoradas.

Mensagens de Erro

Quando dependências não são satisfeitas, o Invowk mostra um erro útil:

✗ Dependencies not satisfied

Command 'deploy' has unmet dependencies:

Missing Tools:
  • docker - not found in PATH
  • kubectl - not found in PATH

Missing Files:
  • Dockerfile - file not found

Missing Environment Variables:
  • AWS_ACCESS_KEY_ID - not set in environment

Install the missing tools and try again.

Exemplo Completo

Aqui está um comando com múltiplos tipos de dependência:

{
    name: "deploy"
    description: "Deploy to production"
    depends_on: {
        // Check environment first
        env_vars: [
            {alternatives: [{name: "AWS_ACCESS_KEY_ID"}, {name: "AWS_PROFILE"}]}
        ]
        // Check required tools
        tools: [
            {alternatives: ["docker", "podman"]},
            {alternatives: ["kubectl"]}
        ]
        // Check required files
        filepaths: [
            {alternatives: ["Dockerfile"]},
            {alternatives: ["k8s/deployment.yaml"]}
        ]
        // Check network connectivity
        capabilities: [
            {alternatives: ["internet"]}
        ]
        // Run other commands first
        cmds: [
            {alternatives: ["build"]},
            {alternatives: ["test"]}
        ]
    }
    implementations: [
        {
            script: "./scripts/deploy.sh"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }
    ]
}

Próximos Passos

Aprenda sobre cada tipo de dependência em detalhes:

• Tools - Verificar binários no PATH
• Filepaths - Verificar arquivos e diretórios
• Commands - Use cmds para exigir que outros comandos estejam disponíveis
• Capabilities - Verificar capacidades do sistema
• Variáveis de Ambiente - Verificar variáveis de ambiente
• Verificações Personalizadas - Escrever scripts de validação personalizados