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

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:

TipoVerifica
toolsBinários no PATH
filepathsArquivos ou diretórios
cmdsOutros comandos Invowk
capabilitiesCapacidades do sistema
env_varsVariáveis de ambiente
custom_checksScripts 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. cmds - Outros comandos Invowk
  6. custom_checks - Scripts de validação personalizados

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 invkfile:

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.21"}]
            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 são validadas de acordo com o runtime:

RuntimeDependências Verificadas Contra
nativeSistema host
virtualShell virtual com built-ins
containerDentro do container

Isso é poderoso para comandos container:

{
    name: "build"
    implementations: [
        {
            script: "go build ./..."
            runtimes: [{name: "container", image: "golang:1.21"}]
            depends_on: {
                // Verificado DENTRO do container, não no host
                tools: [{alternatives: ["go"]}]
                filepaths: [{alternatives: ["/workspace/go.mod"]}]
            }
        }
    ]
}

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: