Referência de Schema do Invowkfile

Alpha — Schema Pode Mudar

O schema do invowkfile ainda está evoluindo. Campos, tipos e regras de validação podem mudar entre releases enquanto estabilizamos o formato. Sempre verifique o changelog ao fazer upgrade.

Referência completa para o schema do invowkfile. Invowkfiles usam formato CUE para definir comandos. Invowkfiles são validados como structs fechadas, então campos desconhecidos geram erro de validação.

Estrutura Raiz

Todo invowkfile deve definir ao menos um comando em cmds:

#Invowkfile: {
    default_shell?: string    // Optional - override default shell
    workdir?:       string    // Optional - default working directory
    env?:           #EnvConfig      // Optional - global environment
    depends_on?:    #DependsOn      // Optional - global dependencies
    cmds:           [...#Command]   // Required - at least one command
}

Metadados do Módulo Ficam em invowkmod.cue

Campos como module, version, description e requires pertencem a invowkmod.cue e são rejeitados em invowkfile.cue.

default_shell

Tipo: string
Obrigatório: Não
Padrão: Padrão do sistema

Sobrescreve o shell padrão para execução no runtime native.

default_shell: "/bin/bash"
default_shell: "pwsh"

workdir

Tipo: string
Obrigatório: Não
Padrão: Diretório do invowkfile

Diretório de trabalho padrão para todos os comandos. Pode ser absoluto ou relativo à localização do invowkfile.

workdir: "./src"
workdir: "/opt/app"

env

Tipo: #EnvConfig
Obrigatório: Não

Configuração de environment global aplicada a todos os comandos. Veja EnvConfig.

depends_on

Tipo: #DependsOn
Obrigatório: Não

Dependências globais que se aplicam a todos os comandos. Veja DependsOn.

cmds

Tipo: [...#Command]
Obrigatório: Sim (pelo menos um)

Lista de comandos definidos neste invowkfile. Veja Command.

Nota de Migração

O nome do campo é cmds, não commands. Usar commands causará um erro de validação CUE porque o schema define commands?: _|_ (valor bottom) para impor o nome correto.

---

Command

Define um comando executável:

#Command: {
    name:            string               // Required
    description?:    string               // Optional
    implementations: [...#Implementation] // Required - at least one
    env?:            #EnvConfig           // Optional
    workdir?:        string               // Optional
    depends_on?:     #DependsOn           // Optional
    flags?:          [...#Flag]           // Optional
    args?:           [...#Argument]       // Optional
}

name

Tipo: string (padrão: ^[a-zA-Z][a-zA-Z0-9_ -]*$)
Obrigatório: Sim

O identificador do comando. Deve começar com uma letra.

name: "build"
name: "test unit"     // Spaces allowed for subcommand-like behavior
name: "deploy-prod"

description

Tipo: string Obrigatório: Não

Texto de ajuda para o comando. Quando fornecido, deve ser não-vazio (validado pelo padrão regex ^\s*\S.*$ -- strings contendo apenas espaços são rejeitadas).

description: "Build the application for production"

implementations

Tipo: [...#Implementation] Obrigatório: Sim (pelo menos um)

As implementations executáveis. Veja Implementation.

env

Tipo: #EnvConfig Obrigatório: Não

Configuração de environment para este comando. O env no nível de comando é aplicado antes do env no nível de implementation. Veja EnvConfig.

workdir

Tipo: string Obrigatório: Não

Diretório de trabalho para execução do comando. Sobrescreve o workdir do nível raiz, mas pode ser sobrescrito pelo workdir no nível de implementation. Pode ser absoluto ou relativo à localização do invowkfile.

depends_on

Tipo: #DependsOn Obrigatório: Não

Dependências que devem ser satisfeitas antes de executar este comando. Veja DependsOn.

flags

Tipo: [...#Flag]
Obrigatório: Não

Flags de linha de comando para este comando. Veja Flag.

Flags Reservadas

As seguintes flags são reservadas pelo invowk e não podem ser usadas em comandos definidos pelo usuário:

• ivk-env-file (-e), ivk-env-var (-E)
• ivk-env-inherit-mode, ivk-env-inherit-allow, ivk-env-inherit-deny
• ivk-workdir (-w), ivk-runtime (-r), ivk-from (-f)
• ivk-force-rebuild
• ivk-verbose (-v), ivk-config (-c), ivk-interactive (-i)
• help (-h), version

Além disso, qualquer flag que comece com o prefixo ivk-, invowk- ou i- é reservada para flags do sistema.

args

Tipo: [...#Argument]
Obrigatório: Não

Argumentos posicionais para este comando. Veja Argument.

---

Implementation

Define como um comando é executado:

#Implementation: {
    script:      string       // Required - inline script or file path
    runtimes:    [...#RuntimeConfig] & [_, ...]  // Required - runtime configurations
    platforms:   [...#PlatformConfig] & [_, ...]  // Required - at least one platform
    env?:        #EnvConfig   // Optional
    workdir?:    string       // Optional
    depends_on?: #DependsOn   // Optional
}

script

Tipo: string (não vazio)
Obrigatório: Sim

Os comandos de shell a executar OU um caminho para um arquivo de script.

// Inline script
script: "echo 'Hello, World!'"

// Multi-line script
script: """
    echo "Building..."
    go build -o app .
    echo "Done!"
    """

// Script file reference
script: "./scripts/build.sh"
script: "deploy.py"

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

runtimes

Tipo: [...#RuntimeConfig]
Obrigatório: Sim (pelo menos um)

Os runtimes que podem executar esta implementation. O primeiro runtime é o padrão.

// Native only
runtimes: [{name: "native"}]
platforms: [{name: "linux"}, {name: "macos"}]

// Multiple runtimes
runtimes: [
platforms: [{name: "linux"}, {name: "macos"}]
    {name: "native"},
    {name: "virtual"},
]

// Container with options
runtimes: [{
platforms: [{name: "linux"}, {name: "macos"}]
    name: "container"
    image: "golang:1.26"
    volumes: ["./:/app"]
}]

platforms

Tipo: [...#PlatformConfig] Obrigatório: Sim (pelo menos um)

Especifique quais sistemas operacionais esta implementation suporta.

// Linux and macOS only
platforms: [
    {name: "linux"},
    {name: "macos"},
]

env

Tipo: #EnvConfig Obrigatório: Não

Configuração de environment para esta implementation. Mesclado com o env no nível de comando: arquivos da implementation são carregados depois dos arquivos do comando, e variáveis da implementation sobrescrevem as do comando. Veja EnvConfig.

workdir

Tipo: string Obrigatório: Não

Diretório de trabalho para esta implementation. Sobrescreve as configurações de workdir tanto do nível raiz quanto do nível de comando. Pode ser absoluto ou relativo à localização do invowkfile.

depends_on

Tipo: #DependsOn Obrigatório: Não

Dependências que devem ser satisfeitas antes de executar esta implementation. Combinado com o depends_on no nível raiz e de comando. Sempre validado no sistema host, independentemente do runtime selecionado. Para validar dependências dentro do ambiente do runtime (ex: dentro de um container), use depends_on dentro do bloco de runtime. Veja DependsOn.

---

RuntimeConfig

Configuração para um runtime específico:

// Shared base fields (all runtimes)
#RuntimeConfigBase: {
    name:               #RuntimeType
    env_inherit_mode?:  "none" | "allow" | "all"
    env_inherit_allow?: [...string]
    env_inherit_deny?:  [...string]
}

// Native runtime: supports interpreter
#RuntimeConfigNative: close({
    #RuntimeConfigBase
    name:         "native"
    interpreter?: string  // "auto", "python3", "/usr/bin/env perl -w", etc.
})

// Virtual runtime: no additional fields
#RuntimeConfigVirtual: close({
    #RuntimeConfigBase
    name: "virtual"
    // NOTE: interpreter is NOT allowed here (CUE validation error)
})

// Container runtime: image/containerfile + extras
#RuntimeConfigContainer: close({
    #RuntimeConfigBase
    name:              "container"
    interpreter?:      string
    enable_host_ssh?:  bool
    containerfile?:    string  // mutually exclusive with image
    image?:            string  // mutually exclusive with containerfile
    volumes?:          [...string]
    ports?:            [...string]
    depends_on?:       #DependsOn  // validated inside the container environment
})

// Discriminated union of all runtime types
#RuntimeConfig: #RuntimeConfigNative | #RuntimeConfigVirtual | #RuntimeConfigContainer

name

Tipo: "native" | "virtual" | "container"
Obrigatório: Sim

O tipo de runtime.

interpreter

Tipo: string
Disponível para: native, container
Padrão: "auto" (detectar do shebang)

Especifica como executar o script.

// Auto-detect from shebang
interpreter: "auto"

// Specific interpreter
interpreter: "python3"
interpreter: "node"
interpreter: "/usr/bin/ruby"

// With arguments
interpreter: "python3 -u"
interpreter: "/usr/bin/env perl -w"

observação

O runtime virtual usa mvdan/sh e não consegue executar interpretadores não-shell.

env_inherit_mode

Tipo: "none" | "allow" | "all"
Disponível para: native, virtual, container
Padrão: all para native/virtual, none para container

Controla se o ambiente do host é herdado pelo runtime.

env_inherit_allow

Tipo: [...string]
Disponível para: native, virtual, container

Lista de variáveis de ambiente permitidas quando env_inherit_mode é "allow".

env_inherit_deny

Tipo: [...string]
Disponível para: native, virtual, container

Lista de variáveis de ambiente negadas (aplica-se a qualquer modo).

runtimes: [{
    platforms: [{name: "linux"}, {name: "macos"}]
    name:              "container"
    image:             "debian:stable-slim"
    env_inherit_mode:  "allow"
    env_inherit_allow: ["TERM", "LANG"]
    env_inherit_deny:  ["AWS_SECRET_ACCESS_KEY"]
}]

enable_host_ssh

Tipo: bool
Disponível para: container
Padrão: false

Habilita acesso SSH do container de volta para o host. Quando habilitado, o Invowk inicia um servidor SSH e fornece credenciais via variáveis de ambiente:

• INVOWK_SSH_ENABLED
• INVOWK_SSH_HOST
• INVOWK_SSH_PORT
• INVOWK_SSH_USER
• INVOWK_SSH_TOKEN

runtimes: [{
    platforms: [{name: "linux"}, {name: "macos"}]
    name: "container"
    image: "debian:stable-slim"
    enable_host_ssh: true
}]

containerfile / image

Tipo: string
Disponível para: container

Especifique a origem do container. São mutuamente exclusivos.

// Use a pre-built image
image: "debian:stable-slim"
image: "golang:1.26"

// Build from a Containerfile
containerfile: "./Containerfile"
containerfile: "./docker/Dockerfile.build"

volumes

Tipo: [...string]
Disponível para: container

Montagens de volume no formato host:container[:options].

volumes: [
    "./src:/app/src",
    "/tmp:/tmp:ro",
    "${HOME}/.cache:/cache",
]

ports

Tipo: [...string]
Disponível para: container

Mapeamentos de portas no formato host:container.

ports: [
    "8080:80",
    "3000:3000",
]

depends_on

Tipo: #DependsOn Disponível para: container Obrigatório: Não

Dependências validadas dentro do ambiente do container. Diferentemente do depends_on no nível raiz/comando/implementação (que sempre verificam o host), o depends_on no nível de runtime container valida contra o próprio ambiente do container — útil para verificar que a imagem do container possui as ferramentas, arquivos e configuração necessários.

Verificado apenas quando o runtime container é selecionado no momento da execução.

---

PlatformConfig

#PlatformConfig: {
    name: "linux" | "macos" | "windows"
}

---

EnvConfig

Configuração de environment:

#EnvConfig: {
    files?: [...string]         // Dotenv files to load
    vars?:  [string]: string    // Environment variables
}

files

Arquivos dotenv para carregar. Arquivos são carregados em ordem; os últimos sobrescrevem os anteriores.

env: {
    files: [
        ".env",
        ".env.local",
        ".env.${ENVIRONMENT}?",  // '?' means optional
    ]
}

vars

Variáveis de ambiente como pares chave-valor.

env: {
    vars: {
        NODE_ENV: "production"
        DEBUG: "false"
    }
}

---

DependsOn

Especificação de dependências:

#DependsOn: {
    tools?:         [...#ToolDependency]
    cmds?:          [...#CommandDependency]
    filepaths?:     [...#FilepathDependency]
    capabilities?:  [...#CapabilityDependency]
    custom_checks?: [...#CustomCheckDependency]
    env_vars?:      [...#EnvVarDependency]
}

ToolDependency

#ToolDependency: {
    alternatives: [...string]  // At least one - tool names
}

depends_on: {
    tools: [
        {alternatives: ["go"]},
        {alternatives: ["podman", "docker"]},  // Either works
    ]
}

CommandDependency

Nome do Campo

O nome do campo para dependências de comandos é cmds, não commands. Usar commands causará um erro de validação CUE porque o schema define commands?: _|_ (valor bottom) para impor o nome correto do campo.

#CommandDependency: {
    alternatives: [...string]  // Command names
}

FilepathDependency

#FilepathDependency: {
    alternatives: [...string]  // File/directory paths
    readable?:    bool
    writable?:    bool
    executable?:  bool
}

CapabilityDependency

#CapabilityDependency: {
    alternatives: [...("local-area-network" | "internet" | "containers" | "tty")]
}

EnvVarDependency

#EnvVarDependency: {
    alternatives: [...#EnvVarCheck]
}

#EnvVarCheck: {
    name:        string    // Environment variable name
    validation?: string    // Regex pattern
}

CustomCheckDependency

#CustomCheckDependency: #CustomCheck | #CustomCheckAlternatives

#CustomCheck: {
    name:             string  // Check identifier
    check_script:     string  // Script to run
    expected_code?:   int     // Expected exit code (default: 0)
    expected_output?: string  // Regex to match output
}

#CustomCheckAlternatives: {
    alternatives: [...#CustomCheck]
}

---

Flag

Definição de flag de linha de comando:

#Flag: {
    name:          string    // POSIX-compliant name
    description:   string    // Help text
    default_value?: string   // Default value
    type?:         "string" | "bool" | "int" | "float"
    required?:     bool
    short?:        string    // Single character alias
    validation?:   string    // Regex pattern
}

Propriedade	Obrigatório	Descrição
name	Sim	Nome da flag (alfanumérico, hífens, underscores)
description	Sim	Texto de ajuda (deve ser não-vazio)
type	Não	string, bool, int, float (padrão: string)
default_value	Não	Padrão se não fornecido (não combina com required)
required	Não	Deve ser fornecido (não combina com default_value)
short	Não	Alias de uma letra (a-z ou A-Z)
validation	Não	Padrão regex para validação de valor

flags: [
    {
        name: "output"
        short: "o"
        description: "Output file path"
        default_value: "./build"
    },
    {
        name: "verbose"
        short: "v"
        description: "Enable verbose output"
        type: "bool"
    },
]

---

Argument

Definição de argumento posicional:

#Argument: {
    name:          string    // POSIX-compliant name
    description:   string    // Help text
    required?:     bool      // Must be provided
    default_value?: string   // Default if not provided
    type?:         "string" | "int" | "float"
    validation?:   string    // Regex pattern
    variadic?:     bool      // Accepts multiple values (last arg only)
}

Propriedade	Obrigatório	Descrição
name	Sim	Nome do argumento (alfanumérico, hífens, underscores)
description	Sim	Texto de ajuda (deve ser não-vazio)
type	Não	string, int, float (padrão: string; bool não suportado)
default_value	Não	Padrão se não fornecido (não combina com required)
required	Não	Deve ser fornecido (não combina com default_value)
variadic	Não	Aceitar múltiplos valores (apenas permitido no último argumento)
validation	Não	Padrão regex para validação de valor

args: [
    {
        name: "target"
        description: "Build target"
        required: true
    },
    {
        name: "files"
        description: "Files to process"
        variadic: true
    },
]

Variáveis de ambiente para argumentos:

• INVOWK_ARG_<NAME> - O valor do argumento
• Para variádicos: INVOWK_ARG_<NAME>_COUNT, INVOWK_ARG_<NAME>_1, INVOWK_ARG_<NAME>_2, etc.

---

Exemplo Completo

env: {
    files: [".env"]
    vars: {
        APP_NAME: "myapp"
    }
}

cmds: [
    {
        name: "build"
        description: "Build the application"
        
        flags: [
            {
                name: "release"
                short: "r"
                description: "Build for release"
                type: "bool"
            },
        ]
        
        implementations: [
            {
                script: """
                    if [ "$INVOWK_FLAG_RELEASE" = "true" ]; then
                        go build -ldflags="-s -w" -o app .
                    else
                        go build -o app .
                    fi
                    """
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}]
            },
            {
                script: """
                    $flags = if ($env:INVOWK_FLAG_RELEASE -eq "true") { "-ldflags=-s -w" } else { "" }
                    go build $flags -o app.exe .
                    """
                runtimes: [{name: "native", interpreter: "pwsh"}]
                platforms: [{name: "windows"}]
            },
        ]
        
        depends_on: {
            tools: [{alternatives: ["go"]}]
        }
    },
]