Referência de Schema do Invkfile

Alpha — Schema Pode Mudar

O schema do invkfile 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 invkfile. Invkfiles usam formato CUE para definir comandos. Invkfiles são validados como structs fechadas, então campos desconhecidos geram erro de validação.

Estrutura Raiz

Todo invkfile deve definir ao menos um comando em cmds:

#Invkfile: {
    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 invkmod.cue

Campos como module, version, description e requires pertencem a invkmod.cue e são rejeitados em invkfile.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 invkfile

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

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 invkfile. Veja Command.

---

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.

description: "Build the application for production"

implementations

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

As implementations executáveis. Veja Implementation.

flags

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

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

Flags Reservadas

env-file (curta e) e env-var (curta E) são flags de sistema reservadas e não podem ser usadas.

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

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

// Container with options
runtimes: [{
    name: "container"
    image: "golang:1.22"
    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"},
]

---

RuntimeConfig

Configuração para um runtime específico:

#RuntimeConfig: {
    name: "native" | "virtual" | "container"
    
    // Host environment inheritance:
    env_inherit_mode?:  "none" | "allow" | "all"
    env_inherit_allow?: [...string]
    env_inherit_deny?:  [...string]

    // For native and container:
    interpreter?: string
    
    // For container only:
    enable_host_ssh?: bool
    containerfile?:   string
    image?:           string
    volumes?:         [...string]
    ports?:           [...string]
}

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: [{
    name:              "container"
    image:             "alpine:latest"
    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_HOST
• INVOWK_SSH_PORT
• INVOWK_SSH_USER
• INVOWK_SSH_TOKEN

runtimes: [{
    name: "container"
    image: "debian:bookworm-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:bookworm-slim"
image: "golang:1.22"

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

---

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

#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
}

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)
}

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