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: {content: "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. Use script.content para comandos inline. Dentro de módulos invowk, script.file pode referenciar um arquivo de script contido no mesmo módulo.

Scripts Inline

Scripts de uma linha são simples:

script: {content: "echo 'Hello, World!'"}

Scripts multilinha usam aspas triplas:

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

Arquivos de Script Externos

Dentro de um módulo invowk, referencie um arquivo de script contido no módulo em vez de código inline:

// Root/project invowkfile: invoke a project-local script from inline content
script: {content: "./scripts/build.sh"}

// Module invowkfile: reference a file contained in the invowkmod
script: {file: "scripts/deploy.sh"}

script.file é explícito, não detectado por extensão: arquivos sem extensão são válidos, e invowkfiles de raiz/projeto devem chamar scripts locais por script.content.

Quando Usar Scripts Externos

• Inline: Comandos rápidos e simples; mantém tudo em um arquivo
• Externo: Scripts complexos empacotados no módulo; reutilizáveis entre comandos do módulo; mais fáceis 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-sh"},     // Built-in POSIX shell
    {name: "container", image: "debian:stable-slim"}  // Container
]
platforms: [{name: "linux"}, {name: "macos"}]

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

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

# Sobrescreve para usar runtime container
invowk cmd myproject build --ivk-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: {content: "rm -rf build/"}
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        },
        // Windows implementation
        {
            script: {content: "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: {content: "go build ./..."}
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
        },
        // Reproducible container build
        {
            script: {content: "echo building in container"}
            runtimes: [{name: "container", image: "debian:stable-slim"}]
            platforms: [{name: "linux"}]
        }
    ]
}

Plataforma + Runtime Combinados

{
    name: "build"
    implementations: [
        // Linux/macOS with multiple runtime options
        {
            script: {content: "make build"}
            runtimes: [
                {name: "native"},
                {name: "container", image: "debian:stable-slim"}
            ]
            platforms: [{name: "linux"}, {name: "macos"}]
        },
        // Windows native only
        {
            script: {content: "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: {content: "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: {content: "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: {content: "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 --ivk-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: {content: "make build"}
            runtimes: [
                {name: "native"},
                {name: "virtual-sh", allowed_binaries: ["make"], binary_lookup_mode: "host"},
            ]
            platforms: [{name: "linux"}, {name: "macos"}]
        },
        {
            script: {content: "msbuild"}
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        }
    ]
}

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

Listagem de Comandos

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

Available Commands
  (* = default runtime)

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

• [native*, virtual-sh] - Suporta runtimes native (padrão) e virtual-sh
• (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: {content: "make build"}}
        ]
    },
    {
        name: "test"
        implementations: [
            _unixNative & {script: {content: "make test"}}
        ]
    },
    {
        name: "version"
        implementations: [
            _allPlatforms & {script: {content: "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-sh, virtual-lua e container
• Dependências - Declare o que suas implementações precisam