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

Modo Interativo

O modo interativo (-i / --interactive) executa comandos em um buffer de tela alternativo com suporte completo a PTY (pseudo-terminal), permitindo interações ricas no terminal.

Visão Geral​

Quando você executa um comando com -i, o Invowk:

  1. Cria um pseudo-terminal (PTY) para o comando
  2. Exibe a saída em um buffer de tela alternativo (terminal fica limpo)
  3. Encaminha toda entrada de teclado para o comando em execução
  4. Permite rolar e revisar a saída após a conclusão
  5. Suporta componentes TUI embutidos como overlays modais

Uso Básico​

# Run a command in interactive mode
invowk cmd build --invk-interactive

Quando Usar o Modo Interativo​

O modo interativo é especialmente útil para:

# Commands with password prompts
invowk cmd deploy --invk-interactive

# Commands with sudo
invowk cmd system-update --invk-interactive

# SSH sessions
invowk cmd remote-shell --invk-interactive

# Any command with interactive input
invowk cmd database-cli --invk-interactive

Por Que Esses Comandos Precisam Dele​

Sem o modo interativo, stdin não está conectado a um TTY, o que quebra:

  • Prompts de senha (não conseguem ler sua entrada de forma segura)
  • sudo (requer um TTY para entrada de senha)
  • Sessões SSH (precisam de controle total do terminal)
  • Qualquer programa usando readline ou bibliotecas similares

Habilitando por Padrão​

Você pode habilitar o modo interativo por padrão na sua configuração:

// In config file: ~/.config/invowk/config.cue
ui: {
    interactive: true  // Enable by default
}

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

observação

O modo interativo funciona com todos os runtimes: nativo, virtual e container.

Atalhos de Teclado​

Durante a Execução do Comando​

During command execution:
  All keys      → Forwarded to running command
  Ctrl+\        → Emergency quit (force exit)

Toda entrada de teclado é encaminhada diretamente para o comando em execução, permitindo interação completa com prompts de senha, editores e outros programas interativos.

Após a Conclusão do Comando​

Uma vez que o comando termina, você pode revisar a saída:

After command completion:
  ↑/k           → Scroll up one line
  ↓/j           → Scroll down one line
  PgUp/b        → Scroll up half page
  PgDown/f/Space→ Scroll down half page
  Home/g        → Go to top
  End/G         → Go to bottom
  q/Esc/Enter   → Exit and return to terminal

A barra de status mostra:

  • Código de saída do comando
  • Duração da execução
  • Indicador de posição de rolagem

Componentes TUI Embutidos​

Ao executar no modo interativo, componentes TUI chamados de seus scripts são renderizados como overlays modais sobre a saída do comando, ao invés de uma tela separada:

{
    name: "interactive-setup"
    description: "Setup with embedded TUI prompts"
    implementations: [{
        script: """
            # When run with --invk-interactive, TUI components appear as overlays
            NAME=$(invowk tui input --title "Project name:")
            TYPE=$(invowk tui choose --title "Type:" api cli library)
            
            if invowk tui confirm "Create $TYPE project '$NAME'?"; then
                mkdir -p "$NAME"
                echo "Created $NAME"
            fi
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Isso cria uma experiência fluida onde:

  1. Seu script executa na tela alternativa
  2. Quando um componente TUI é necessário, ele aparece como overlay
  3. Após o usuário completar a interação, o overlay fecha
  4. A execução do script continua com o valor capturado

Como Funciona​

Quando um comando executa com -i:

  1. Invowk inicia um servidor TUI local
  2. Processos filhos detectam a variável de ambiente INVOWK_TUI_ADDR
  3. Ao invés de renderizar diretamente, componentes TUI enviam requisições ao pai
  4. O pai os renderiza como overlays modais
  5. Resultados são enviados de volta ao processo filho

Isso acontece automaticamente - nenhuma mudança necessária nos seus scripts.

Buffer de Tela Alternativo​

O buffer de tela alternativo é um recurso do terminal que:

  • Fornece uma "tela" separada para o comando
  • Preserva seu histórico do terminal
  • Restaura automaticamente quando o comando termina

Isso significa que após sair do modo interativo:

  • Seu terminal parece exatamente como antes
  • Sem poluição de saída no seu scrollback
  • Separação limpa entre saída do invowk e uso normal do terminal

Limitações​

  • Comando único: Não é possível executar múltiplos comandos em paralelo no modo interativo
  • PTY necessário: O terminal deve suportar operações PTY
  • Apenas containers glibc: Imagens de container devem ser baseadas em glibc (não Alpine/musl)

Suporte ao Runtime Container​

O modo interativo funciona perfeitamente com o runtime container. As execuções em container já usam a camada de imagem auto-provisionada (habilitada por padrão) para que invowk esteja disponível dentro do container; o modo interativo adiciona a infraestrutura de TUI. Veja Runtime Container para detalhes. Quando você executa um comando de container com -i:

  1. Camada de imagem provisionada: Invowk garante que seu binário esteja disponível (mesmo comportamento do modo não interativo)
  2. Servidor TUI: Um servidor local trata requisições TUI do container
  3. Overlays modais: Componentes TUI renderizam no seu terminal, não dentro do container
# Executar um comando de container interativamente
invowk cmd myproject build -i -r container

Dentro dos scripts do seu container, você pode usar todos os componentes TUI:

{
    name: "deploy"
    implementations: [{
        script: """
            # Componentes TUI funcionam dentro de containers!
            ENV=$(invowk tui choose "Selecione o ambiente" "dev" "staging" "prod")
            
            if invowk tui confirm "Deploy em $ENV?"; then
                ./deploy.sh "$ENV"
            fi
            """
        runtimes: [{
            name: "container"
            image: "debian:bookworm-slim"
        }]
    }]
}
glibc Necessário

Imagens de container devem usar glibc (não musl). Imagens baseadas em Alpine não são suportadas. Use Debian, Ubuntu, ou imagens sem o sufixo -alpine.

Boas Práticas​

  1. Use para comandos que precisam de entrada: Scripts de deploy com confirmações, migrações de banco de dados, etc.

  2. Não use para comandos simples: Comandos rápidos sem interação não se beneficiam do modo interativo

  3. Combine com componentes TUI: Crie fluxos de trabalho interativos ricos com prompts embutidos

  4. Considere o padrão de configuração: Se a maioria dos seus comandos precisa de interação, habilite na configuração

Exemplos​

Script de Deploy​

{
    name: "deploy"
    description: "Deploy com confirmações"
    implementations: [{
        script: """
            echo "Fazendo deploy em produção..."
            
            # Este prompt de sudo funciona porque estamos no modo interativo
            sudo systemctl restart myapp
            
            echo "Deploy concluído!"
            """
        runtimes: [{name: "native"}]
    }]
}

Execute com: invowk cmd myproject deploy -i

Migração de Banco de Dados​

{
    name: "db migrate"
    description: "Executar migrações do banco de dados"
    implementations: [{
        script: """
            echo "=== Migração de Banco de Dados ==="
            
            # Confirmação interativa
            if invowk tui confirm "Aplicar migrações em produção?"; then
                # Prompt de senha funciona no modo interativo
                psql -h prod-db -U admin -W -f migrations.sql
            fi
            """
        runtimes: [{name: "native"}]
    }]
}

Próximos Passos​