Versão: 0.5.0

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
    category?:       string               // Optional - groups in listing
    implementations: [...#Implementation] // Required - at least one
    env?:            #EnvConfig           // Optional
    workdir?:        string               // Optional
    depends_on?:     #DependsOn           // Optional
    flags?:          [...#Flag]           // Optional
    args?:           [...#Argument]       // Optional
    watch?:          #WatchConfig         // Optional - file-watching
}

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-dry-run
ivk-watch (-W)
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.

watch

Tipo: #WatchConfig Obrigatório: Não

Configuração de file-watching para este comando. Quando definido, patterns controla quais arquivos são monitorados. Quando --ivk-watch é passado sem uma configuração watch, o invowk monitora todos os arquivos (**/*) no diretório de trabalho. Veja WatchConfig.

{
    name: "dev"
    description: "Run development server with auto-reload"
    watch: {
        patterns: ["src/**/*.go", "*.go"]
        debounce: "1s"
        clear_screen: true
        ignore: ["vendor/**"]
    }
    implementations: [{
        script: "go run ./cmd/server"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

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
    timeout?:    #DurationString  // Optional - max execution time
}

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.

timeout

Tipo: #DurationString Obrigatório: Não

Duração máxima de execução. Deve ser uma string de duração Go válida (ex: "30s", "5m", "1h30m"). Quando excedido, o comando é cancelado e retorna um erro de timeout. O valor de timeout é validado cedo (antes das verificações de dependência) para falhar rapidamente em valores inválidos. Veja DurationString.

{
    name: "build"
    implementations: [{
        script: "make build"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
        timeout: "5m"
    }]
}

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.

WatchConfig

Configuração de file-watching para reexecução automática de comandos:

#WatchConfig: {
    patterns:      [...string] & [_, ...] // Required - glob patterns to watch
    debounce?:     #DurationString        // Optional - default "500ms"
    clear_screen?: bool                   // Optional - default false
    ignore?:       [...string]            // Optional - merged with built-in defaults
}

patterns

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

Padrões glob para arquivos a monitorar. Padrões suportam ** para correspondência recursiva (ex: "src/**/*.go", "*.ts"). Caminhos são relativos ao diretório de trabalho efetivo do comando.

debounce

Tipo: #DurationString Obrigatório: Não Padrão: "500ms"

Atraso antes de reexecutar após detectar uma mudança de arquivo. Veja DurationString.

clear_screen

Tipo: bool Obrigatório: Não Padrão: false

Quando true, limpa o terminal antes de cada reexecução.

ignore

Tipo: [...string] Obrigatório: Não

Padrões glob adicionais para arquivos/diretórios a excluir do monitoramento. Mesclados com padrões padrão embutidos (.git/**, node_modules/**, __pycache__/**, *.swp, etc.).

DurationString

// #DurationString — shared by timeout and debounce
// Valid examples: "500ms", "30s", "5m", "1h30m", "2.5s"
#DurationString: string & =~"^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$"

Tipo compartilhado usado por #Implementation.timeout e #WatchConfig.debounce. Exemplos válidos: "500ms", "30s", "5m", "1h30m", "2.5s".

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"]}]
        }
    },
]

Estrutura Raiz​

default_shell​

workdir​

env​

depends_on​

cmds​

Command​

name​

description​

category​

implementations​

env​

workdir​

depends_on​

flags​

args​

watch​

Implementation​

script​

runtimes​

platforms​

env​

workdir​

depends_on​

timeout​

RuntimeConfig​

name​

interpreter​

env_inherit_mode​

env_inherit_allow​

env_inherit_deny​

enable_host_ssh​

containerfile / image​

volumes​

ports​

depends_on​

PlatformConfig​

EnvConfig​

files​

vars​

DependsOn​

ToolDependency​

CommandDependency​

FilepathDependency​

CapabilityDependency​

EnvVarDependency​

CustomCheckDependency​

Flag​

Argument​

WatchConfig​

patterns​

debounce​

clear_screen​

ignore​

DurationString​

Exemplo Completo​

Estrutura Raiz

default_shell

workdir

env

depends_on

cmds

Command

name

description

category

implementations

env

workdir

depends_on

flags

args

watch

Implementation

script

runtimes

platforms

env

workdir

depends_on

timeout

RuntimeConfig

name

interpreter

env_inherit_mode

env_inherit_allow

env_inherit_deny

enable_host_ssh

containerfile / image

volumes

ports

depends_on

PlatformConfig

EnvConfig

files

vars

DependsOn

ToolDependency

CommandDependency

FilepathDependency

CapabilityDependency

EnvVarDependency

CustomCheckDependency

Flag

Argument

WatchConfig

patterns

debounce

clear_screen

ignore

DurationString

Exemplo Completo