Dependências de Ferramentas

Dependências de ferramentas verificam se os binários necessários estão disponíveis no PATH antes que seu comando seja executado.

Uso Básico

depends_on: {
    tools: [
        {alternatives: ["go"]}
    ]
}

Se go não for encontrado no PATH, o comando falha com um erro claro:

$ 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.

Alternativas (Semântica OU)

Especifique múltiplas alternativas quando qualquer ferramenta funcionar:

depends_on: {
    tools: [
        {alternatives: ["docker", "podman"]},
        {alternatives: ["node", "nodejs"]}
    ]
}

O Invowk™ verifica as alternativas em ordem e para na primeira correspondência. Isso é útil para:

• Ferramentas com alternativas compatíveis (docker/podman)
• Preferências de editor (nvim/vim/vi)
• Variantes de versão (python3/python)

Múltiplos Requisitos de Ferramentas

Cada entrada em tools é um requisito E:

depends_on: {
    tools: [
        // Need (podman OR docker) AND kubectl AND helm
        {alternatives: ["podman", "docker"]},
        {alternatives: ["kubectl"]},
        {alternatives: ["helm"]},
    ]
}

Todos os três devem ser satisfeitos (embora alternativas dentro de cada um sejam OU).

Exemplos do Mundo Real

Projeto Go

{
    name: "build"
    depends_on: {
        tools: [
            {alternatives: ["go"]},
            {alternatives: ["git"]},  // For version info
        ]
    }
    implementations: [{
        script: """
            VERSION=$(git describe --tags --always)
            go build -ldflags="-X main.version=$VERSION" ./...
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Projeto Node.js

{
    name: "build"
    depends_on: {
        tools: [
            // Prefer pnpm, but npm works too
            {alternatives: ["pnpm", "npm", "yarn"]},
            {alternatives: ["node"]},
        ]
    }
    implementations: [{
        script: "pnpm run build || npm run build"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Deploy Kubernetes

{
    name: "deploy"
    depends_on: {
        tools: [
            {alternatives: ["kubectl"]},
            {alternatives: ["helm"]},
            {alternatives: ["podman", "docker"]},
        ]
    }
    implementations: [{
        script: """
            helm upgrade --install myapp ./charts/myapp
            kubectl rollout status deployment/myapp
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Projeto Python

{
    name: "run"
    depends_on: {
        tools: [
            // Python 3 with various possible names
            {alternatives: ["python3", "python"]},
            // Virtual environment tool
            {alternatives: ["poetry", "pipenv", "pip"]},
        ]
    }
    implementations: [{
        script: "poetry run python main.py"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Validação Consciente do Runtime

Verificações de ferramentas são validadas de acordo com o runtime:

Runtime Native

Ferramentas são verificadas no sistema host:

{
    name: "build"
    depends_on: {
        tools: [{alternatives: ["go"]}]  // Checked on host
    }
    implementations: [{
        script: "go build ./..."
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Runtime Virtual

Ferramentas são verificadas no ambiente do shell virtual:

{
    name: "build"
    depends_on: {
        tools: [{alternatives: ["go"]}]  // Checked in virtual shell
    }
    implementations: [{
        script: "go build ./..."
        runtimes: [{name: "virtual"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Runtime Container

Ferramentas são verificadas dentro do container:

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

Isso é especialmente útil porque:

• O host não precisa ter Go instalado
• Você está validando o ambiente de execução real
• Você detecta ferramentas faltando em imagens de container personalizadas

Padrões Comuns

Verificar Antes de Chamada Externa

{
    name: "upload"
    depends_on: {
        tools: [{alternatives: ["aws", "aws-cli"]}]
    }
    implementations: [{
        script: "aws s3 sync ./dist s3://my-bucket"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Ferramentas de Banco de Dados

{
    name: "db migrate"
    depends_on: {
        tools: [
            {alternatives: ["psql", "pgcli"]},  // PostgreSQL client
            {alternatives: ["migrate", "goose", "flyway"]},  // Migration tool
        ]
    }
    implementations: [{
        script: "migrate -path ./migrations -database $DATABASE_URL up"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Multiplataforma

{
    name: "open docs"
    depends_on: {
        tools: [
            // Platform-specific openers
            {alternatives: ["xdg-open", "open", "start"]},
        ]
    }
    implementations: [{
        script: "xdg-open http://localhost:3000/docs || open http://localhost:3000/docs"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Melhores Práticas

1. Use alternativas para ferramentas compatíveis: {alternatives: ["podman", "docker"]}
2. Ordene alternativas por preferência: A primeira alternativa é verificada primeiro
3. Mantenha listas de ferramentas mínimas: Requer apenas o que é realmente usado
4. Considere o contexto do runtime: Ferramentas de container são verificadas dentro de containers

Próximos Passos

• Filepaths - Verificar arquivos necessários
• Commands - Depender de outros comandos Invowk