Runtime Virtual

O runtime virtual usa o interpretador de shell POSIX-compatível integrado do Invowk™ (powered by mvdan/sh). Ele fornece comportamento de shell consistente em todas as plataformas sem exigir um shell externo.

Como Funciona

Quando você executa um comando com o runtime virtual, o Invowk:

1. Faz o parse do script usando o parser de shell integrado
2. Executa-o em um ambiente embarcado tipo POSIX
3. Fornece utilitários core (echo, test, etc.) integrados

Uso Básico

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

invowk cmd build --ivk-runtime virtual

Consistência Multiplataforma

O runtime virtual se comporta de forma idêntica no Linux, macOS e Windows:

{
    name: "setup"
    implementations: [{
        script: """
            # This works the same everywhere!
            if [ -d "node_modules" ]; then
                echo "Dependencies already installed"
            else
                echo "Installing dependencies..."
                npm install
            fi
            """
        runtimes: [{name: "virtual"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Chega de "funciona na minha máquina" para scripts shell!

Utilitários Integrados

O shell virtual inclui utilitários POSIX core:

Utilitário	Descrição
echo	Imprimir texto
printf	Saída formatada
test / [	Condicionais
true / false	Sair com 0/1
pwd	Imprimir diretório de trabalho
cd	Mudar diretório
read	Ler entrada
export	Definir variáveis de ambiente

Utilitários Estendidos (u-root)

Quando habilitado na configuração, utilitários adicionais estão disponíveis:

// In your config file
virtual_shell: {
    enable_uroot_utils: true
}

Isso adiciona utilitários como:

• cat, head, tail
• grep, sed, awk
• ls, cp, mv, rm
• mkdir, rmdir
• E muitos outros

Recursos do Shell POSIX

O shell virtual suporta construções POSIX padrão:

Variáveis

script: """
    NAME="World"
    echo "Hello, $NAME!"
    
    # Parameter expansion
    echo "${NAME:-default}"
    echo "${#NAME}"  # Length
    """

Condicionais

script: """
    if [ "$ENV" = "production" ]; then
        echo "Production mode"
    elif [ "$ENV" = "staging" ]; then
        echo "Staging mode"
    else
        echo "Development mode"
    fi
    """

Loops

script: """
    # For loop
    for file in *.go; do
        echo "Processing $file"
    done
    
    # While loop
    count=0
    while [ $count -lt 5 ]; do
        echo "Count: $count"
        count=$((count + 1))
    done
    """

Funções

script: """
    greet() {
        echo "Hello, $1!"
    }
    
    greet "World"
    greet "Invowk"
    """

Subshells e Substituição de Comandos

script: """
    # Command substitution
    current_date=$(date +%Y-%m-%d)
    echo "Today is $current_date"
    
    # Subshell
    (cd /tmp && echo "In temp: $(pwd)")
    echo "Still in: $(pwd)"
    """

Chamando Comandos Externos

O shell virtual pode chamar comandos externos instalados no seu sistema:

script: """
    # Calls the real 'go' binary
    go version
    
    # Calls the real 'git' binary
    git status
    """

Comandos externos são encontrados usando o PATH do sistema.

Variáveis de Ambiente

Variáveis de ambiente funcionam da mesma forma que no native:

{
    name: "build"
    env: {
        vars: {
            BUILD_MODE: "release"
        }
    }
    implementations: [{
        script: """
            echo "Building in $BUILD_MODE mode"
            go build -ldflags="-s -w" ./...
            """
        runtimes: [{name: "virtual"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Flags e Argumentos

Acesse flags e argumentos da mesma forma:

{
    name: "greet"
    args: [{name: "name", default_value: "World"}]
    implementations: [{
        script: """
            # Using environment variable
            echo "Hello, $INVOWK_ARG_NAME!"

            # Or positional parameter
            echo "Hello, $1!"
            """
        runtimes: [{name: "virtual"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Limitações

Sem Suporte a Interpretadores

O runtime virtual não pode usar interpretadores não-shell:

// This will NOT work with virtual runtime!
{
    name: "bad-example"
    implementations: [{
        script: """
            #!/usr/bin/env python3
            print("This won't work!")
            """
        runtimes: [{
            name: "virtual"
            interpreter: "python3"  // ERROR: Not supported
        }]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Para Python, Ruby ou outros interpretadores, use o runtime native ou container.

Recursos Específicos do Bash

Alguns recursos específicos do bash não estão disponíveis:

// These won't work in virtual runtime:
script: """
    # Bash arrays (use $@ instead)
    declare -a arr=(1 2 3)  # Not supported
    
    # Bash-specific parameter expansion
    ${var^^}  # Uppercase - not supported
    ${var,,}  # Lowercase - not supported
    
    # Process substitution
    diff <(cmd1) <(cmd2)  # Not supported
    """

Mantenha construções POSIX-compatíveis para o runtime virtual.

Validação de Dependências

Dependências são validadas contra as capacidades do shell virtual:

{
    name: "build"
    depends_on: {
        tools: [
            // These will be checked in the virtual shell environment
            {alternatives: ["go"]},
            {alternatives: ["git"]}
        ]
    }
    implementations: [{
        script: "go build ./..."
        runtimes: [{name: "virtual"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Vantagens

• Consistência: Mesmo comportamento no Linux, macOS e Windows
• Sem dependência de shell: Funciona mesmo se o shell do sistema não estiver disponível
• Portabilidade: Scripts funcionam em todas as plataformas
• Utilitários integrados: Utilitários core sempre disponíveis
• Startup mais rápido: Sem processo de shell para iniciar

Quando Usar Virtual

• Scripts multiplataforma: Quando o mesmo script deve funcionar em todos os lugares
• Pipelines CI/CD: Comportamento consistente entre agentes de build
• Scripts shell simples: Quando você não precisa de recursos específicos do bash
• Ambientes embarcados: Quando shells externos não estão disponíveis

Configuração

Configure o shell virtual no seu arquivo de configuração do Invowk:

// ~/.config/invowk/config.cue (Linux)
// ~/Library/Application Support/invowk/config.cue (macOS)
// %APPDATA%\invowk\config.cue (Windows)

virtual_shell: {
    // Enable additional utilities from u-root
    enable_uroot_utils: true
}

Próximos Passos

• Runtime Native - Para acesso completo ao shell
• Runtime Container - Para execução isolada