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

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​

// Baixar dependências
{
    name: "deps"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: "go mod download"
        runtimes: [{name: "native"}]
    }]
}

// Deploy para a nuvem
{
    name: "deploy"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: "kubectl apply -f k8s/"
        runtimes: [{name: "native"}]
    }]
}

// Buscar dados remotos
{
    name: "sync"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: "curl -o data.json https://api.example.com/data"
        runtimes: [{name: "native"}]
    }]
}

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​

// Conectar ao banco de dados local
{
    name: "db connect"
    depends_on: {
        capabilities: [{alternatives: ["local-area-network"]}]
    }
    implementations: [{
        script: "psql -h db.local -U admin"
        runtimes: [{name: "native"}]
    }]
}

// Acessar serviços locais
{
    name: "check services"
    depends_on: {
        capabilities: [{alternatives: ["local-area-network"]}]
    }
    implementations: [{
        script: "curl http://service.local:8080/health"
        runtimes: [{name: "native"}]
    }]
}

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: [
        // Internet OU LAN serve
        {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: "Instalar dependências do projeto"
    depends_on: {
        capabilities: [{alternatives: ["internet"]}]
        tools: [{alternatives: ["npm", "pnpm", "yarn"]}]
    }
    implementations: [{
        script: "npm install"
        runtimes: [{name: "native"}]
    }]
}

Pipeline de CI​

{
    name: "ci"
    description: "Executar pipeline de CI com verificações remotas"
    depends_on: {
        capabilities: [
            {alternatives: ["internet"]}  // Para download de dependências
        ]
        tools: [
            {alternatives: ["go"]},
            {alternatives: ["git"]},
        ]
    }
    implementations: [{
        script: """
            go mod download
            go build ./...
            go test ./...
            """
        runtimes: [{name: "native"}]
    }]
}

Ambiente Híbrido​

{
    name: "backup"
    description: "Fazer backup para armazenamento disponível"
    depends_on: {
        // Pode fazer backup para nuvem (internet) ou 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"}]
    }]
}

Padrão Offline-First​

Projete comandos que funcionam offline quando possível:

cmds: [
    // Versão online - baixa o mais recente
    {
        name: "update deps"
        depends_on: {
            capabilities: [{alternatives: ["internet"]}]
        }
        implementations: [{
            script: "go mod download"
            runtimes: [{name: "native"}]
        }]
    },
    
    // Versão offline - usa cache
    {
        name: "build"
        // Sem requisito de internet - usa dependências em cache
        depends_on: {
            filepaths: [{alternatives: ["go.mod"]}]
        }
        implementations: [{
            script: "go build -mod=readonly ./..."
            runtimes: [{name: "native"}]
        }]
    }
]

Contexto de Container​

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

{
    name: "deploy"
    depends_on: {
        // Verificação de internet acontece no HOST
        capabilities: [{alternatives: ["internet"]}]
    }
    implementations: [{
        script: "kubectl apply -f k8s/"
        runtimes: [{name: "container", image: "bitnami/kubectl"}]
    }]
}

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​