Pular para o conteúdo principal
Versão: 0.3.0

Formato do Invowkfile

Invowkfiles são escritos em CUE, uma linguagem de configuração poderosa que é como JSON com superpoderes. Se você nunca usou CUE antes, não se preocupe - é intuitivo e você vai aprender rapidamente.

Por que CUE?​

Escolhemos CUE em vez de YAML ou JSON porque:

  • Validação integrada - CUE detecta erros antes de você executar qualquer coisa
  • Sem pesadelos de indentação - Diferente do YAML, um espaço mal posicionado não vai quebrar tudo
  • Comentários! - Sim, você pode realmente escrever comentários
  • Tipagem segura - O schema do Invowk™ garante que seu invowkfile está correto
  • Templates - Reduza repetição com o poderoso sistema de templates do CUE

Sintaxe Básica​

CUE parece com JSON, mas mais legível:

// This is a comment

// Lists use square brackets
cmds: [
    {
        name: "hello"
        description: "A greeting command"
    }
]

// Multi-line strings use triple quotes
script: """
    echo "Line 1"
    echo "Line 2"
    """

Diferenças principais do JSON:

  • Vírgulas não são necessárias após campos (embora sejam permitidas)
  • Vírgulas finais são aceitas
  • Comentários com //
  • Strings multilinha com """

Visão Geral do Schema​

Todo invowkfile segue esta estrutura:

// Root level
default_shell?: string  // Optional: override default shell
workdir?: string        // Optional: default working directory
env?: #EnvConfig        // Optional: global environment config
depends_on?: #DependsOn // Optional: global dependencies

// Required: at least one command
cmds: [...#Command] & [_, ...]  // at least one required

O sufixo ? significa que um campo é opcional.

Namespaces via Módulos​

Invowkfiles definem comandos sem namespace. Se você quiser namespacing, coloque seus comandos em um módulo e defina o ID do módulo em invowkmod.cue.

Veja Comandos e Namespaces para regras de nomes e prefixos.

Estrutura de Comandos​

Cada comando tem esta estrutura:

{
    name: string                 // Required: command name
    description?: string         // Optional: help text
    implementations: [...]       // Required: how to run the command
    flags?: [...]                // Optional: command flags
    args?: [...]                 // Optional: positional arguments
    env?: #EnvConfig             // Optional: environment config
    workdir?: string             // Optional: working directory
    depends_on?: #DependsOn      // Optional: dependencies
}

Implementações​

Um comando pode ter múltiplas implementações para diferentes plataformas/runtimes:

{
    name: "build"
    implementations: [
        // Unix implementation
        {
            script: "make build"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        },
        // Windows implementation
        {
            script: "msbuild /p:Configuration=Release"
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        }
    ]
}

O Invowk automaticamente escolhe a implementação correta para sua plataforma.

Scripts​

Scripts podem ser inline ou referenciar arquivos externos:

Scripts Inline​

// Single line
script: "echo 'Hello!'"

// Multi-line
script: """
    #!/bin/bash
    set -e
    echo "Building..."
    go build ./...
    """

Arquivos de Script Externos​

// Relative to invowkfile location
script: "./scripts/build.sh"

// Just the filename (recognized extensions)
script: "deploy.sh"

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

Exemplo Completo​

Aqui está um invowkfile com todos os recursos:

// Global environment
env: {
    vars: {
        APP_NAME: "myapp"
        LOG_LEVEL: "info"
    }
}

// Global dependencies
depends_on: {
    tools: [{alternatives: ["sh", "bash"]}]
}

cmds: [
    {
        name: "build"
        description: "Build the application"
        implementations: [
            {
                script: """
                    echo "Building $APP_NAME..."
                    go build -o bin/$APP_NAME ./...
                    """
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
            }
        ]
        depends_on: {
            tools: [{alternatives: ["go"]}]
            filepaths: [{alternatives: ["go.mod"]}]
        }
    },
    {
        name: "deploy"
        description: "Deploy to production"
        implementations: [
            {
                script: "./scripts/deploy.sh"
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}]
            }
        ]
        depends_on: {
            tools: [{alternatives: ["docker", "podman"]}]
            cmds: [{alternatives: ["build"]}]
        }
        flags: [
            {name: "env", description: "Target environment", required: true},
            {name: "dry-run", description: "Simulate deployment", type: "bool", default_value: "false"}
        ]
    }
]

Dicas e Truques do CUE​

Reduzir Repetição​

Use o sistema de templates do CUE para evitar repetição:

// Define a template
_nativeUnix: {
    runtimes: [{name: "native"}]
    platforms: [{name: "linux"}, {name: "macos"}]
}

cmds: [
    {
        name: "build"
        implementations: [
            _nativeUnix & {script: "make build"}
        ]
    },
    {
        name: "test"
        implementations: [
            _nativeUnix & {script: "make test"}
        ]
    }
]

Validação​

Execute seu invowkfile através do validador CUE:

cue vet invowkfile.cue path/to/invowkfile_schema.cue -d '#Invowkfile'

Ou apenas tente listar comandos - o Invowk valida automaticamente:

invowk cmd

Próximos Passos​