Pular para o conteúdo principal
Versão: 0.1.0-alpha.1

Referência de Schema do Invkfile

:::warning 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
}

:::note 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.

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