Versão: 0.1.0-alpha.2

Referência de Schema de Configuração

Alpha — Opções de Configuração Podem Mudar

O schema de configuração ainda está sendo refinado. Opções podem ser adicionadas, renomeadas ou removidas entre releases enquanto finalizamos o conjunto de funcionalidades.

Referência completa para o schema do arquivo de configuração do Invowk™.

Visão Geral

O arquivo de configuração usa formato CUE e está localizado em:

Plataforma	Localização
Linux	`~/.config/invowk/config.cue`
macOS	`~/Library/Application Support/invowk/config.cue`
Windows	`%APPDATA%\invowk\config.cue`

Arquivos de configuração são validados com structs fechadas, então campos desconhecidos geram erro de validação.

Definição do Schema

// Root configuration structure
#Config: {
    container_engine?: "podman" | "docker"
    includes?:         [...#IncludeEntry]
    default_runtime?:  "native" | "virtual" | "container"
    virtual_shell?:    #VirtualShellConfig
    ui?:               #UIConfig
    container?:        #ContainerConfig
}

// Include entry for invkfiles and modules
#IncludeEntry: {
    path:   string  // Must end with .invkmod, /invkfile.cue, or /invkfile
    alias?: string  // Optional, only valid for .invkmod paths
}

// Virtual shell configuration
#VirtualShellConfig: {
    enable_uroot_utils?: bool
}

// UI configuration
#UIConfig: {
    color_scheme?: "auto" | "dark" | "light"
    verbose?:      bool
    interactive?:  bool
}

// Container configuration
#ContainerConfig: {
    auto_provision?: #AutoProvisionConfig
}

// Auto-provisioning configuration
#AutoProvisionConfig: {
    enabled?:     bool
    binary_path?: string
    modules_paths?: [...string]
    cache_dir?:   string
}

Config

O objeto de configuração raiz.

#Config: {
    container_engine?: "podman" | "docker"
    includes?:         [...#IncludeEntry]
    default_runtime?:  "native" | "virtual" | "container"
    virtual_shell?:    #VirtualShellConfig
    ui?:               #UIConfig
    container?:        #ContainerConfig
}

container_engine

Tipo: "podman" | "docker"
Obrigatório: Não
Padrão: "podman"

Especifica qual container runtime usar para execução de comandos baseada em container.

container_engine: "podman"

Se a engine preferida não estiver disponível, o Invowk faz fallback para a outra quando o runtime container é necessário.

search_paths

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

Diretórios adicionais para buscar invkfiles e módulos.

search_paths: [
    "~/.invowk/cmds",
    "~/projects/shared-commands",
    "/opt/company/invowk-commands",
]

Resolução de caminho:

Caminhos começando com ~ são expandidos para o diretório home do usuário
Caminhos relativos são resolvidos do diretório de trabalho atual
Caminhos inexistentes são ignorados silenciosamente

Prioridade de busca (maior para menor):

Diretório atual
Caminhos em search_paths (em ordem)
~/.invowk/cmds

default_runtime

Tipo: "native" | "virtual" | "container"
Obrigatório: Não
Padrão: "native"

Define o modo de runtime padrão global para comandos que não especificam um runtime preferido.

default_runtime: "virtual"

Valor	Descrição
`"native"`	Executar usando o shell nativo do sistema
`"virtual"`	Executar usando o interpretador de shell embutido do Invowk
`"container"`	Executar dentro de um container

virtual_shell

Tipo: #VirtualShellConfig
Obrigatório: Não
Padrão: {}

Configuração para o virtual shell runtime.

virtual_shell: {
    enable_uroot_utils: true
}

ui

Tipo: #UIConfig
Obrigatório: Não
Padrão: {}

Configuração de interface do usuário.

ui: {
    color_scheme: "dark"
    verbose: false
    interactive: false
}

container

Tipo: #ContainerConfig
Obrigatório: Não
Padrão: {}

Configuração para o runtime container.

container: {
    auto_provision: {
        enabled: true
    }
}

VirtualShellConfig

Configuração para o virtual shell runtime (mvdan/sh).

#VirtualShellConfig: {
    enable_uroot_utils?: bool
}

enable_uroot_utils

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

Habilita utilitários u-root no ambiente virtual shell. Quando habilitado, fornece comandos adicionais além dos builtins básicos de shell.

virtual_shell: {
    enable_uroot_utils: true
}

Utilitários disponíveis quando habilitado:

Operações de arquivo: ls, cat, cp, mv, rm, mkdir, chmod
Processamento de texto: grep, sed, awk, sort, uniq
E muitos mais utilitários core

UIConfig

Configuração de interface do usuário.

#UIConfig: {
    color_scheme?: "auto" | "dark" | "light"
    verbose?:      bool
    interactive?:  bool
}

color_scheme

Tipo: "auto" | "dark" | "light"
Obrigatório: Não
Padrão: "auto"

Define o esquema de cores para saída de terminal.

ui: {
    color_scheme: "auto"
}

Valor	Descrição
`"auto"`	Detectar do terminal (respeita `COLORTERM`, `TERM`, etc.)
`"dark"`	Cores otimizadas para terminais escuros
`"light"`	Cores otimizadas para terminais claros

verbose

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

Habilita saída verbose por padrão para todos os comandos.

ui: {
    verbose: true
}

Equivalente a sempre passar --verbose na linha de comando.

interactive

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

Habilita o modo interativo por padrão (buffer de tela alternativo com PTY).

ui: {
    interactive: true
}

ContainerConfig

Configuração para comportamento do runtime container.

#ContainerConfig: {
    auto_provision?: #AutoProvisionConfig
}

auto_provision

Tipo: #AutoProvisionConfig
Obrigatório: Não
Padrão: {}

Controla o provisionamento automático de recursos do invowk dentro de containers.

container: {
    auto_provision: {
        enabled: true
        binary_path: "/usr/local/bin/invowk"
        modules_paths: ["/opt/company/invowk-modules"]
        cache_dir: "/tmp/invowk/provision"
    }
}

Com o auto-provisionamento habilitado, o Invowk cria uma imagem derivada em cache ao anexar uma pequena camada de provisionamento sobre a imagem base. Isso ocorre em toda execução de container (interativa ou não); se o provisionamento falhar, o Invowk avisa e usa a imagem base.

AutoProvisionConfig

Configuração de auto-provisionamento para imagens container.

#AutoProvisionConfig: {
    enabled?:     bool
    binary_path?: string
    modules_paths?: [...string]
    cache_dir?:   string
}

enabled

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

Habilita o provisionamento automático do binário do invowk e módulos em containers.

binary_path

Tipo: string
Obrigatório: Não
Padrão: (vazio; usa o binário do invowk em execução)

Sobrescreve o caminho do binário do invowk para provisionar.

modules_paths

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

Diretórios adicionais de módulos para provisionar em containers.

cache_dir

Tipo: string
Obrigatório: Não
Padrão: ~/.cache/invowk/provision

Sobrescreve o diretório de cache para metadados de imagens provisionadas.

Exemplo Completo

Um arquivo de configuração totalmente documentado:

// Invowk Configuration File
// =========================
// Location: ~/.config/invowk/config.cue

// Container Engine
// ----------------
// Which container runtime to use: "podman" or "docker"
container_engine: "podman"

// Includes
// --------
// Additional invkfiles and modules to include in discovery.
// Each entry specifies a path to an invkfile.cue, invkfile, or *.invkmod.
// Modules may have an optional alias for collision disambiguation.
includes: [
    // Personal commands
    {path: "~/.invowk/cmds/invkfile.cue"},

    // Team shared module (with alias)
    {path: "~/work/shared.invkmod", alias: "team"},

    // Organization-wide module
    {path: "/opt/company/tools.invkmod"},
]

// Default Runtime
// ---------------
// The runtime to use when a command doesn't specify one
// Options: "native", "virtual", "container"
default_runtime: "native"

// Virtual Shell Configuration
// ---------------------------
// Settings for the virtual shell runtime (mvdan/sh)
virtual_shell: {
    // Enable u-root utilities for more shell commands
    // Provides ls, cat, grep, etc. in the virtual environment
    enable_uroot_utils: true
}

// UI Configuration
// ----------------
// User interface settings
ui: {
    // Color scheme: "auto", "dark", or "light"
    // "auto" detects from terminal settings
    color_scheme: "auto"
    
    // Enable verbose output by default
    // Same as always passing --invk-verbose
    verbose: false

    // Enable interactive mode by default
    interactive: false
}

// Container provisioning
// ----------------------
container: {
    auto_provision: {
        enabled: true
    }
}

Configuração Mínima

Se você está satisfeito com os padrões, uma configuração mínima pode ser:

// Just override what you need
container_engine: "docker"

Ou até mesmo um arquivo vazio (todos os padrões):

// Empty config - use all defaults

Validação

Você pode validar seu arquivo de configuração usando CUE:

cue vet ~/.config/invowk/config.cue

Ou verificá-lo com Invowk:

invowk config show

Se houver algum erro, Invowk irá reportá-los ao carregar a configuração.

Visão Geral​

Definição do Schema​

Config​

container_engine​

search_paths​

default_runtime​

virtual_shell​

ui​

container​

VirtualShellConfig​

enable_uroot_utils​

UIConfig​

color_scheme​

verbose​

interactive​

ContainerConfig​

auto_provision​

AutoProvisionConfig​

enabled​

binary_path​

modules_paths​

cache_dir​

Exemplo Completo​

Configuração Mínima​

Validação​