Pular para o conteúdo principal
Versão: 0.4.0

Dependências de Capacidades

Dependências de capacidades verificam se capacidades de sistema necessárias estão disponíveis antes que seu comando seja executado. O Invowk™ suporta conectividade de rede, disponibilidade de engine de containers e verificação de TTY interativo.

Capacidades Disponíveis​

CapacidadeDescrição
local-area-networkVerifica conectividade de rede local (LAN)
internetVerifica conectividade com a internet
containersVerifica se Docker ou Podman está instalado e respondendo
ttyVerifica se o Invowk está rodando em um TTY interativo

Uso Básico​

depends_on: {
    capabilities: [
        {alternatives: ["internet"]},
        {alternatives: ["local-area-network"]}
    ]
}

Se a conectividade com a internet não estiver disponível:

✗ Dependencies not satisfied

Command 'deploy' has unmet dependencies:

Missing Capabilities:
  • internet - no internet connectivity

Ensure the required capabilities are available and try again.

Conectividade com a Internet​

Verifique se há acesso à internet funcionando:

depends_on: {
    capabilities: [
        {alternatives: ["internet"]}
    ]
}

Isso verifica:

  • Resolução de DNS está funcionando
  • Consegue alcançar hosts externos
  • Rede não está bloqueada

Casos de Uso​

// Download dependencies
{
    name: "deps"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: "go mod download"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

// Deploy to cloud
{
    name: "deploy"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: "kubectl apply -f k8s/"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

// Fetch remote data
{
    name: "sync"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: "curl -o data.json https://api.example.com/data"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Rede Local (LAN)​

Verifique conectividade de rede local:

depends_on: {
    capabilities: [
        {alternatives: ["local-area-network"]}
    ]
}

Isso verifica:

  • Interface de rede está ativa
  • Pode comunicar na rede local
  • Útil para serviços on-premise

Casos de Uso​

// Connect to local database
{
    name: "db connect"
    depends_on: {
        capabilities: [{alternatives: ["local-area-network"]}]
    }
    implementations: [{
        script: "psql -h db.local -U admin"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

// Access local services
{
    name: "check services"
    depends_on: {
        capabilities: [{alternatives: ["local-area-network"]}]
    }
    implementations: [{
        script: "curl http://service.local:8080/health"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Engine de Containers​

Verifique se um engine de containers está instalado e pronto:

depends_on: {
    capabilities: [
        {alternatives: ["containers"]}
    ]
}

Isso verifica:

  • Docker ou Podman está no PATH
  • O engine responde ao comando de versão

Casos de Uso​

Use isso quando um comando chama Docker/Podman diretamente ou precisa de builds de container.

TTY Interativo​

Verifique se o Invowk está rodando em um terminal interativo:

depends_on: {
    capabilities: [
        {alternatives: ["tty"]}
    ]
}

Isso verifica:

  • stdin é um terminal
  • stdout é um terminal

Casos de Uso​

Use isso para prompts interativos, componentes TUI ou scripts que exigem entrada de teclado.

Alternativas (Semântica OU)​

Requer qualquer uma das capacidades:

depends_on: {
    capabilities: [
        // Either internet OR LAN is fine
        {alternatives: ["internet", "local-area-network"]}
    ]
}

Isso é útil quando um comando pode funcionar com:

  • Serviços de nuvem remotos (internet)
  • Serviços on-premise locais (LAN)

Exemplos do Mundo Real​

Instalação de Pacotes​

{
    name: "install"
    description: "Install project dependencies"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
        tools: [{alternatives: ["npm", "pnpm", "yarn"]}]
    }
    implementations: [{
        script: "npm install"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Pipeline de CI​

{
    name: "ci"
    description: "Run CI pipeline with remote checks"
    depends_on: {
        capabilities: [
            {alternatives: ["internet"]}  // For dependency download
        ]
        tools: [
            {alternatives: ["go"]},
            {alternatives: ["git"]},
        ]
    }
    implementations: [{
        script: """
            go mod download
            go build ./...
            go test ./...
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Ambiente Híbrido​

{
    name: "backup"
    description: "Backup to available storage"
    depends_on: {
        // Can backup to cloud (internet) or NAS (LAN)
        capabilities: [{alternatives: ["internet", "local-area-network"]}]
    }
    implementations: [{
        script: """
            if ping -c 1 nas.local > /dev/null 2>&1; then
                rsync -av ./data nas.local:/backup/
            else
                aws s3 sync ./data s3://my-backup-bucket/
            fi
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Padrão Offline-First​

Projete comandos que funcionam offline quando possível:

cmds: [
    // Online version - downloads latest
    {
        name: "update deps"
        depends_on: {
            capabilities: [{alternatives: ["internet"]}]
        }
        implementations: [{
            script: "go mod download"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }]
    },

    // Offline version - uses cache
    {
        name: "build"
        // No internet requirement - uses cached dependencies
        depends_on: {
            filepaths: [{alternatives: ["go.mod"]}]
        }
        implementations: [{
            script: "go build -mod=readonly ./..."
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }]
    }
]

Contexto de Container​

Para runtime container, verificações de capacidade são realizadas no host, não dentro do container:

{
    name: "deploy"
    depends_on: {
        // Internet check happens on HOST
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: """
            apt-get update && apt-get install -y kubectl
            kubectl apply -f k8s/
            """
        runtimes: [{name: "container", image: "debian:stable-slim"}]
        platforms: [{name: "linux"}]
    }]
}

Isso faz sentido porque:

  • Rede do container herda do host
  • Você está verificando se o deploy pode alcançar serviços externos
  • Rede do container é efêmera

Melhores Práticas​

  1. Verifique apenas quando necessário: Não exija internet para tarefas que funcionam offline
  2. Use alternativas: Quando serviços locais ou de nuvem são intercambiáveis
  3. Falhe rápido: Verifique conectividade antes de iniciar operações longas
  4. Forneça fallbacks: Ofereça alternativas offline quando possível

Próximos Passos​