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 modules
#IncludeEntry: {
    path:   string  // Must end with .invowkmod
    alias?: string  // Optional, for collision disambiguation
}

// 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
    includes?:         [...#IncludeEntry]
    inherit_includes?: bool
    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.

includes

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

Módulos adicionais para incluir na descoberta de comandos. Cada entrada especifica um caminho para um diretório *.invowkmod com um alias opcional para desambiguação de colisões.

includes: [
    {path: "~/.invowk/modules/tools.invowkmod"},
    {path: "~/projects/shared.invowkmod", alias: "shared"},
    {path: "/opt/company/tools.invowkmod"},
]

Requisitos de caminho:

• Caminhos devem ser absolutos e terminar com .invowkmod
• Caminhos inexistentes são ignorados silenciosamente
• Caminhos duplicados são rejeitados

Regras de alias:

• Aliases são opcionais, para desambiguação de colisões
• Cada alias deve ser único entre todas as entradas includes

Prioridade de descoberta (maior para menor):

1. invowkfile do diretório atual
2. Módulos locais (*.invowkmod no diretório atual)
3. ~/.invowk/cmds
4. includes configurados (em ordem)

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 (15 no total):

• Operações de arquivo (7): cat, cp, ls, mkdir, mv, rm, touch
• Processamento de texto (8): head, tail, wc, grep, sort, uniq, cut, tr

---

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 --ivk-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"
        includes: [
            {path: "/opt/company/modules/tools.invowkmod"},
        ]
        inherit_includes: true
        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
    includes?:         [...#IncludeEntry]
    inherit_includes?: bool
    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.

includes

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

Módulos adicionais para provisionar em containers. Usa o mesmo formato #IncludeEntry do includes raiz (cada entrada tem um path terminando com .invowkmod e um alias opcional).

inherit_includes

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

Quando true, as entradas de includes do nível raiz são automaticamente herdadas pelo auto-provisionamento. Defina como false para provisionar apenas os módulos listados explicitamente em container.auto_provision.includes.

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 modules to include in discovery.
// Each entry specifies a path to an *.invowkmod directory.
// Modules may have an optional alias for collision disambiguation.
includes: [
    // Personal modules
    {path: "~/.invowk/modules/tools.invowkmod"},

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

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

// 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 --ivk-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.