Visão Geral dos Modos de Runtime

O Invowk™ oferece três formas diferentes de executar comandos, cada uma com seus próprios pontos fortes. Escolha o runtime certo para seu caso de uso.

Os Três Runtimes

Runtime	Descrição	Melhor Para
native	Shell padrão do sistema	Desenvolvimento diário, performance
virtual	Shell POSIX integrado	Scripts multiplataforma, portabilidade
container	Container Docker/Podman	Reprodutibilidade, isolamento

Comparação Rápida

cmds: [
    // Native: uses your system shell (bash, zsh, PowerShell, etc.)
    {
        name: "build native"
        implementations: [{
            script: "go build ./..."
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
        }]
    },

    // Virtual: uses built-in POSIX-compatible shell
    {
        name: "build virtual"
        implementations: [{
            script: "go build ./..."
            runtimes: [{name: "virtual"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
        }]
    },

    // Container: runs inside a container
    {
        name: "build container"
        implementations: [{
            script: "go build -o /workspace/bin/app ./..."
            runtimes: [{name: "container", image: "golang:1.26"}]
            platforms: [{name: "linux"}]
        }]
    }
]

Quando Usar Cada Runtime

Runtime Native

Use native quando você quiser:

• Máxima performance
• Acesso a todas as ferramentas do sistema
• Recursos específicos do shell (bash completions, plugins do zsh)
• Integração com seu ambiente de desenvolvimento

{
    name: "build"
    implementations: [
        {
            script: "go build ./..."
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
        }
    ]
}

Runtime Virtual

Use virtual quando você quiser:

• Comportamento consistente entre plataformas
• Scripts POSIX-compatíveis que funcionam em qualquer lugar
• Sem dependência de shell externo (o interpretador é integrado, mas scripts ainda podem chamar binários do host via PATH)
• Debug mais simples de scripts shell

cuidado

O runtime virtual não é um sandbox. Comandos não fornecidos pelos utilitários integrados são resolvidos a partir do PATH do host e executados como processos nativos. Para isolamento de execução, use o runtime container.

{
    name: "build"
    implementations: [{
        script: """
            echo "Building..."
            go build -o bin/app ./...
            echo "Done!"
            """
        runtimes: [{name: "virtual"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Runtime Container

Use container quando você quiser:

• Builds reproduzíveis
• Ambientes isolados
• Versões específicas de ferramentas
• Execução em ambiente limpo

{
    name: "build"
    implementations: [
        {
            script: "echo 'Hello from container' && ls /workspace"
            runtimes: [{
                name: "container"
                image: "debian:stable-slim"
            }]
            platforms: [{name: "linux"}]
        }
    ]
}

Múltiplos Runtimes Por Comando

Comandos podem suportar múltiplos runtimes. O primeiro é o padrão:

{
    name: "build"
    implementations: [
        {
            script: "go build ./..."
            runtimes: [
                {name: "native"},  // Default
                {name: "virtual"}, // Alternative
            ]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
        },
        {
            script: "go build ./..."
            runtimes: [
                {name: "container", image: "golang:1.26"}  // Reproducible
            ]
            platforms: [{name: "linux"}]  // Container runtime is Linux-only
        },
    ]
}

Sobrescrevendo em Tempo de Execução

# Use default (native)
invowk cmd build

# Override to virtual
invowk cmd build --ivk-runtime virtual

# Override to container
invowk cmd build --ivk-runtime container

Listagem de Comandos

A lista de comandos mostra runtimes disponíveis com um asterisco marcando o padrão:

Available Commands
  (* = default runtime)

From invowkfile:
  build - Build the project [native*, virtual, container] (linux, macos)

Fluxo de Seleção de Runtime

O runtime é resolvido usando um modelo de precedência de 3 níveis:

1. Flag CLI (--ivk-runtime) — Sobrescrita rígida. Erro se o runtime especificado não for compatível com o comando na plataforma atual.
2. Runtime padrão do config (default_runtime no config) — Sobrescrita flexível. Se o runtime padrão do config for compatível com o comando, é usado. Caso contrário, passa silenciosamente para o Nível 3.
3. Padrão por comando — Primeiro runtime da primeira implementação correspondente para a plataforma atual.

                    ┌──────────────────┐
                    │  invowk cmd run  │
                    └────────┬─────────┘
                             │
                  ┌──────────▼───────────┐
                  │ Nível 1: flag        │
                  │ --ivk-runtime?       │
                  └──────────┬───────────┘
                             │
              ┌──────────────┴──────────────┐
              │ Sim                         │ Não
              ▼                             ▼
    ┌─────────────────────┐      ┌──────────────────────┐
    │ Usar runtime        │      │ Nível 2: config      │
    │ especificado (erro  │      │ default_runtime      │
    │ se incompatível)    │      │ definido?            │
    └─────────────────────┘      └──────────┬───────────┘
                                            │
                                ┌───────────┴────────────┐
                                │ Sim & compatível       │ Não / incompatível
                                ▼                        ▼
                     ┌─────────────────────┐   ┌─────────────────────┐
                     │ Usar runtime padrão │   │ Nível 3: padrão por │
                     │ do config           │   │ comando (primeiro   │
                     └─────────────────────┘   │ runtime compatível) │
                                               └─────────────────────┘

Validação de Dependências

Dependências são validadas de acordo com o runtime:

Runtime	Dependências Validadas Contra
native	Shell e ferramentas do sistema host
virtual	Shell integrado com utilitários core
container	Shell e ambiente do container

Isso significa que uma dependência tools como go é verificada:

• native: O go está no PATH do host?
• virtual: O go está disponível nos built-ins do shell virtual?
• container: O go está instalado na imagem do container?

Próximos Passos

Aprofunde-se em cada runtime:

• Runtime Native - Execução no shell do sistema
• Runtime Virtual - Shell POSIX integrado
• Runtime Container - Execução em Docker/Podman