Visão Geral dos Modos de Runtime

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

Os Quatro Runtimes

Runtime	Descrição	Melhor Para
native	Shell padrão do sistema	Desenvolvimento diário, performance
virtual-sh	Shell POSIX integrado	Scripts shell multiplataforma, portabilidade
virtual-lua	Interpretador Lua integrado	Automação Lua multiplataforma
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: {content: "go build ./..."}
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
        }]
    },

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

    // Container: runs inside a container
    {
        name: "build container"
        implementations: [{
            script: {content: "echo building in container"}
            runtimes: [{name: "container", image: "debian:stable-slim"}]
            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: {content: "go build ./..."}
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
        }
    ]
}

Runtime Virtual-Sh

Use virtual-sh 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, e scripts podem chamar binários do host explicitamente permitidos)
• Debug mais simples de scripts shell

cuidado

O runtime virtual-sh não é um sandbox. Binários do host são negados a menos que sejam listados explicitamente em allowed_binaries. Para isolamento de execução, use o runtime container.

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

Runtime Virtual-Lua

Use virtual-lua quando você quiser:

• Automação Lua portátil sem exigir um binário Lua no host
• Scripts estruturados com tabelas, funções e require local ao módulo
• E/S de arquivos validada por caminho pelo harness virtual do Invowk
• Chamadas explícitas da ponte para utilitários e binários do host permitidos

cuidado

O runtime virtual-lua não é um sandbox. Binários do host permitidos ainda executam como processos nativos. Para isolamento de execução, use o runtime container.

{
    name: "hello-lua"
    implementations: [{
        script: {content: """
            print("Hello from virtual-lua")
            print("workdir: " .. invowk.path("@work"))
            """}
        runtimes: [{name: "virtual-lua"}]
        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: {content: "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: {content: "go build ./..."}
            runtimes: [
                {name: "native"},  // Default
                {name: "virtual-sh", allowed_binaries: ["go"], binary_lookup_mode: "host"}, // Alternative
            ]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
        },
        {
            script: {content: "echo building in container"}
            runtimes: [
                {name: "container", image: "debian:stable-slim"}  // Reproducible
            ]
            platforms: [{name: "linux"}]  // Container runtime is Linux-only
        },
    ]
}

Sobrescrevendo em Tempo de Execução

# Use default (native)
invowk cmd build

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

# 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-sh, 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

Entradas depends_on no nível raiz, comando e implementação são sempre validadas contra o sistema host, independentemente do runtime selecionado. depends_on no nível de runtime só está disponível em configurações de runtime container, onde valida dependências dentro do ambiente do container.

Escopo	Dependências Validadas Contra
depends_on de raiz / comando / implementação	Sistema host
depends_on do runtime container	Ambiente da imagem do container

Isso significa que uma dependência tools no nível do comando, como go, verifica se go está disponível no host. Para verificar se go está instalado dentro de uma imagem de container, coloque essa dependência dentro do bloco de runtime container.

Próximos Passos

Aprofunde-se em cada runtime:

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