Opções de Configuração

Esta página documenta todas as opções de configuração disponíveis para o Invowk™.

Schema de Configuração

O arquivo de configuração usa o formato CUE e segue este schema:

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

#IncludeEntry: {
    path:   string  // Must end with .invkmod
    alias?: string  // Optional, for collision disambiguation
}

#VirtualShellConfig: {
    enable_uroot_utils?: bool
}

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

#ContainerConfig: {
    auto_provision?: #AutoProvisionConfig
}

#AutoProvisionConfig: {
    enabled?: bool
    binary_path?: string
    includes?: [...#IncludeEntry]
    inherit_includes?: bool
    cache_dir?: string
}

Campos desconhecidos são rejeitados, então mantenha o arquivo de configuração limitado às opções do schema.

Referência de Opções

container_engine

Tipo: "podman" | "docker"
Padrão: "podman"

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

container_engine: "docker"  // or "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] Padrão: []

Módulos adicionais para incluir na descoberta de comandos. Cada entrada é um #IncludeEntry com path obrigatório (deve terminar com .invkmod) e alias opcional.

includes: [
    {path: "~/.invowk/modules/tools.invkmod"},
    {path: "~/my-company/shared.invkmod", alias: "company"},
]

Requisitos de caminho:

• Deve terminar com .invkmod
• Caminhos duplicados são rejeitados

Regras de alias:

• Opcional, para desambiguação de colisões
• Deve ser único entre todas as entradas includes

Ordem de Descoberta:

1. invkfile do diretório atual (sempre buscado primeiro, maior prioridade)
2. Módulos locais (*.invkmod no diretório atual)
3. ~/.invowk/cmds (sempre incluído)
4. Cada entrada em includes em ordem

Comandos de entradas anteriores sobrescrevem comandos com o mesmo nome de entradas posteriores.

default_runtime

Tipo: "native" | "virtual" | "container"
Padrão: "native"

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

default_runtime: "virtual"

Opções de Runtime:

• "native" - Executar usando o shell nativo do sistema (bash, zsh, PowerShell, etc.)
• "virtual" - Executar usando o interpretador de shell embutido do Invowk (mvdan/sh)
• "container" - Executar dentro de um container (requer Docker ou Podman)

observação

Comandos podem sobrescrever este padrão especificando seu próprio runtime no campo implementations.

virtual_shell

Tipo: #VirtualShellConfig
Padrão: {}

Configura o comportamento do virtual shell runtime.

virtual_shell: {
    enable_uroot_utils: true
}

virtual_shell.enable_uroot_utils

Tipo: bool
Padrão: true

Habilita utilitários u-root no virtual shell. Quando habilitado, comandos adicionais como ls, cat, grep e outros ficam disponíveis no ambiente virtual shell.

virtual_shell: {
    enable_uroot_utils: true
}

Isso é útil quando você quer que o virtual shell tenha mais capacidades além dos builtins básicos de shell, enquanto ainda evita execução de shell nativo.

ui

Tipo: #UIConfig
Padrão: {}

Configura as preferências de interface do usuário.

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

ui.color_scheme

Tipo: "auto" | "dark" | "light"
Padrão: "auto"

Define o esquema de cores para a saída do Invowk.

ui: {
    color_scheme: "auto"
}

Opções:

• "auto" - Detectar das configurações do terminal (respeita COLORTERM, TERM, etc.)
• "dark" - Usar cores otimizadas para terminais escuros
• "light" - Usar cores otimizadas para terminais claros

ui.verbose

Tipo: bool
Padrão: false

Habilita saída verbose por padrão. Quando habilitado, Invowk imprime informações adicionais sobre descoberta de comandos, validação de dependências e execução.

ui: {
    verbose: true
}

Isso é equivalente a sempre passar --invk-verbose na linha de comando.

ui.interactive

Tipo: bool
Padrão: false

Habilita o modo interativo por padrão. Quando habilitado, os comandos são executados em um buffer de tela alternativo com suporte completo a PTY, permitindo que programas interativos como prompts de senha, confirmações e outras interações baseadas em stdin funcionem corretamente.

ui: {
    interactive: true
}

Isso é equivalente a sempre passar --invk-interactive na linha de comando.

container

Tipo: #ContainerConfig
Padrão: {}

Configura o comportamento do runtime container.

container: {
    auto_provision: {
        enabled: true
        binary_path: "/usr/local/bin/invowk"
        includes: [
            {path: "/opt/company/modules/tools.invkmod"},
        ]
        inherit_includes: true
        cache_dir: "/tmp/invowk/provision"
    }
}

container.auto_provision.enabled

Tipo: bool
Padrão: true

Habilita o provisionamento automático do binário do invowk e módulos dentro dos containers. Quando habilitado, o Invowk cria uma imagem derivada em cache para cada execução de container, anexando uma pequena camada de provisionamento sobre a imagem base. Se o provisionamento falhar, o Invowk avisa e usa a imagem base.

container.auto_provision.binary_path

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

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

container.auto_provision.includes

Tipo: [...#IncludeEntry] Padrão: []

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

container.auto_provision.inherit_includes

Tipo: bool 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.

container.auto_provision.cache_dir

Tipo: string
Padrão: ~/.cache/invowk/provision

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

Exemplo Completo

Aqui está um arquivo de configuração completo com todas as opções:

// Invowk Configuration File
// Located at: ~/.config/invowk/config.cue

// Use Podman as the container engine
container_engine: "podman"

// Additional modules to include in discovery
includes: [
    {path: "~/.invowk/modules/tools.invkmod"},       // Personal modules
    {path: "~/work/shared.invkmod", alias: "team"},   // Team shared module
]

// Default to virtual shell for portability
default_runtime: "virtual"

// Virtual shell settings
virtual_shell: {
    // Enable u-root utilities for more shell commands
    enable_uroot_utils: true
}

// UI preferences
ui: {
    // Auto-detect color scheme from terminal
    color_scheme: "auto"
    
    // Don't be verbose by default
    verbose: false
    
    // Enable interactive mode for commands with stdin (e.g., password prompts)
    interactive: false
}

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