Implementações

Todo comando precisa de pelo menos uma implementação - o código real que executa quando você invoca o comando. Implementações definem o que executa, onde executa (plataforma), e como executa (runtime).

Estrutura Básica

Uma implementação tem três partes principais:

{
    name: "build"
    implementations: [
        {
            // 1. The script to run
            script: "go build ./..."
            
            // 2. Target constraints (runtime + platform)
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }
    ]
}

Scripts

O campo script contém os comandos a serem executados. Pode ser inline ou referenciar um arquivo externo.

Scripts Inline

Scripts de uma linha são simples:

script: "echo 'Hello, World!'"

Scripts multilinha usam aspas triplas:

script: """
    #!/bin/bash
    set -e
    echo "Building..."
    go build -o bin/app ./...
    echo "Done!"
    """

Arquivos de Script Externos

Referencie um arquivo de script em vez de código inline:

// Relative to invkfile location
script: "./scripts/build.sh"

// Just the filename (recognized extensions)
script: "deploy.sh"

Extensões reconhecidas: .sh, .bash, .ps1, .bat, .cmd, .py, .rb, .pl, .zsh, .fish

Quando Usar Scripts Externos

• Inline: Comandos rápidos e simples; mantém tudo em um arquivo
• Externo: Scripts complexos; reutilizáveis entre comandos; mais fácil de editar com syntax highlighting

Restrições de Runtime e Plataforma

Cada implementação especifica onde e como executa usando os campos runtimes e platforms.

Runtimes

Toda implementação deve especificar pelo menos um runtime:

runtimes: [
    {name: "native"},      // System shell
    {name: "virtual"},     // Built-in POSIX shell
    {name: "container", image: "debian:bookworm-slim"}  // Container
]

O primeiro runtime é o padrão. Usuários podem sobrescrever com --runtime:

# Usa o runtime padrão (primeiro da lista)
invowk cmd myproject build

# Sobrescreve para usar runtime container
invowk cmd myproject build --runtime container

Veja Modos de Runtime para detalhes sobre cada runtime.

Plataformas

Especifique quais sistemas operacionais a implementação suporta. Toda implementação deve declarar pelo menos uma plataforma:

runtimes: [{name: "native"}]
platforms: [
    {name: "linux"},
    {name: "macos"},
    {name: "windows"}
]

Plataformas disponíveis: linux, macos, windows

Múltiplas Implementações

Comandos podem ter múltiplas implementações para diferentes cenários:

Implementações Específicas por Plataforma

{
    name: "clean"
    implementations: [
        // Unix implementation
        {
            script: "rm -rf build/"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        },
        // Windows implementation
        {
            script: "rmdir /s /q build"
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        }
    ]
}

O Invowk™ automaticamente seleciona a implementação correta para a plataforma atual.

Implementações Específicas por Runtime

{
    name: "build"
    implementations: [
        // Fast native build
        {
            script: "go build ./..."
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
        },
        // Reproducible container build
        {
            script: "go build -o /workspace/bin/app ./..."
            runtimes: [{name: "container", image: "golang:1.21"}]
            platforms: [{name: "linux"}]
        }
    ]
}

Plataforma + Runtime Combinados

{
    name: "build"
    implementations: [
        // Linux/macOS com múltiplas opções de runtime
        {
            script: "make build"
            runtimes: [
                {name: "native"},
                {name: "container", image: "ubuntu:22.04"}
            ]
            platforms: [{name: "linux"}, {name: "macos"}]
        },
        // Windows apenas nativo
        {
            script: "msbuild /p:Configuration=Release"
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        }
    ]
}

Ambiente Específico por Plataforma

Para variáveis de ambiente específicas por plataforma, use implementações separadas por plataforma, cada uma com seu próprio env:

{
    name: "deploy"
    implementations: [
        // Linux implementation with platform-specific env
        {
            script: "echo \"Deploying to $PLATFORM with config at $CONFIG_PATH\""
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}]
            env: {
                vars: {
                    PLATFORM: "Linux"
                    CONFIG_PATH: "/etc/app/config.yaml"
                }
            }
        },
        // macOS implementation with platform-specific env
        {
            script: "echo \"Deploying to $PLATFORM with config at $CONFIG_PATH\""
            runtimes: [{name: "native"}]
            platforms: [{name: "macos"}]
            env: {
                vars: {
                    PLATFORM: "macOS"
                    CONFIG_PATH: "/usr/local/etc/app/config.yaml"
                }
            }
        }
    ]
}

Configurações no Nível da Implementação

Implementações podem ter seu próprio ambiente, diretório de trabalho e dependências:

{
    name: "build"
    implementations: [
        {
            script: "npm run build"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]

            // Implementation-specific env
            env: {
                vars: {
                    NODE_ENV: "production"
                }
            }
            
            // Implementation-specific workdir
            workdir: "./frontend"
            
            // Implementation-specific dependencies
            depends_on: {
                tools: [{alternatives: ["node", "npm"]}]
                filepaths: [{alternatives: ["package.json"]}]
            }
        }
    ]
}

Estas sobrescrevem configurações do nível do comando quando esta implementação é selecionada.

Seleção de Implementação

Quando você executa um comando, o Invowk seleciona uma implementação baseado em:

1. Plataforma atual - Filtra para implementações que suportam seu SO
2. Runtime solicitado - Se --runtime especificado, usa esse; caso contrário usa o padrão
3. Primeiro match vence - Usa a primeira implementação que corresponde a ambos os critérios

Exemplos de Seleção

Dado este comando:

{
    name: "build"
    implementations: [
        {
            script: "make build"
            runtimes: [{name: "native"}, {name: "virtual"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        },
        {
            script: "msbuild"
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        }
    ]
}

Plataforma	Comando	Selecionado
Linux	invowk cmd myproject build	Primeira impl, runtime native
Linux	invowk cmd myproject build --runtime virtual	Primeira impl, runtime virtual
Windows	invowk cmd myproject build	Segunda impl, runtime native
Windows	invowk cmd myproject build --runtime virtual	Erro: nenhuma impl correspondente

Listagem de Comandos

A saída de invowk cmd --list mostra runtimes e plataformas disponíveis:

Available Commands
  (* = default runtime)

From current directory:
  build - Build the project [native*, virtual] (linux, macos)
  clean - Clean artifacts [native*] (linux, macos, windows)
  docker-build - Container build [container*] (linux, macos, windows)

• [native*, virtual] - Suporta runtimes native (padrão) e virtual
• (linux, macos) - Disponível apenas no Linux e macOS

Usando Templates CUE

Reduza repetição com templates CUE:

// Define reusable templates
_unixNative: {
    runtimes: [{name: "native"}]
    platforms: [{name: "linux"}, {name: "macos"}]
}

_allPlatforms: {
    runtimes: [{name: "native"}]
    platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
}

cmds: [
    {
        name: "build"
        implementations: [
            _unixNative & {script: "make build"}
        ]
    },
    {
        name: "test"
        implementations: [
            _unixNative & {script: "make test"}
        ]
    },
    {
        name: "version"
        implementations: [
            _allPlatforms & {script: "cat VERSION"}
        ]
    }
]

Boas Práticas

1. Comece simples - Uma implementação é frequentemente suficiente
2. Sempre especifique plataformas - Toda implementação deve declarar pelo menos uma plataforma alvo
3. Runtime padrão primeiro - Coloque o runtime mais comum primeiro na lista
4. Use templates - Reduza repetição com o sistema de templates do CUE
5. Mantenha scripts focados - Uma tarefa por comando; encadeie com dependências

Próximos Passos

• Modos de Runtime - Mergulho profundo nos runtimes native, virtual e container
• Dependências - Declare o que suas implementações precisam