Diagrama de Sequência de Execução de Comandos

Este diagrama mostra o fluxo temporal desde a invocação do CLI através da descoberta, seleção de runtime e execução. Entender este fluxo ajuda com debugging e extensão do Invowk.

Fluxo Principal de Execução

Fluxo do Runtime Container (Detalhado)

Quando o runtime container é selecionado, etapas adicionais ocorrem. O caminho padrão é um run --rm efêmero; quando persistent é configurado ou --ivk-container-name é fornecido, o Invowk resolve/inspeciona um container de destino e executa com docker exec ou podman exec.

Fluxo do Runtime Virtual-Sh

O runtime virtual-sh usa o interpretador mvdan/sh embutido:

Descrições das Fases

1. Fase de Inicialização

Etapa	Componente	Ação
1	CLI	Receber comando do usuário
2-4	Config + CUE	Carregar e fazer parsing do arquivo global de config resolvido

Decisões-chave tomadas:

• Preferência de engine de container (docker vs podman)
• Includes configurados para invowkfiles/módulos
• Runtime padrão se não especificado

2. Fase de Descoberta

Etapa	Componente	Ação
5	Discovery	Iniciar descoberta de comandos
6-7	CUE Parser	Fazer parsing de todos os arquivos invowkfile.cue
8-9	Discovery	Escanear diretórios *.invowkmod e invowk_modules/ vendorizados
10	Discovery	Construir árvore unificada de comandos

Ordem de precedência (maior para menor):

1. invowkfile.cue do diretório atual
2. *.invowkmod do diretório atual
3. Includes configurados
4. Diretório de comandos do usuário ~/.invowk/cmds/ (apenas módulos, não recursivo)

3. Fase de Resolução

Etapa	Componente	Ação
11	Command Service	Corresponder nome do comando aos comandos descobertos
12	Command Service	Selecionar implementação específica da plataforma
13	Command Service	Resolver runtime usando override da CLI, default da configuração ou default do comando
14	Command Service	Construir contexto de execução
15	Command Service	Retornar plano dry-run quando --ivk-dry-run estiver ativo, antes da validação de dependências ou setup de host/runtime

Correspondência de plataforma:

• Verificar platforms: [{name: "linux"}], [{name: "macos"}], [{name: "windows"}]
• Erro se nenhuma implementação corresponder à plataforma atual

4. Fase de Execução

Etapa	Componente	Ação
16	Command Service	Iniciar acesso opcional ao host e criar sessão de runtime
17	Command Service	Aplicar timeout e validar dependências
18	Registry	Buscar runtime selecionado e validar disponibilidade
19	Runtime Selecionado	Executar o script/comando real
20	Runtime	Retornar resultado
21	CLI	Saída para usuário

Comportamento específico do runtime:

• Native: Spawns processo do shell do host
• Virtual-Sh: Interpreta via mvdan/sh
• Virtual-Lua: Interpreta via golua com o harness de segurança virtual compartilhado
• Container: Provisiona uma imagem e executa um container efêmero com tratamento de retry transitório ou executa via Exec em um alvo persistente
• Ciclo de vida SSH/TUI: Gerenciado pela orquestração de comandos (CommandService), não pela implementação de runtime em si

5. Interceptação Dry-Run

Quando --ivk-dry-run é passado, o pipeline é interrompido após a resolução:

Etapa	Componente	Ação
1	CLI	Detectar flag --ivk-dry-run
2	Command Service	Executar descoberta, validação de entrada, resolução de runtime e construção do contexto de execução
3	CLI	Imprimir plano de execução resolvido (Comando, Fonte, Runtime, Plataforma, WorkDir, Timeout, Script, Ambiente)
4	CLI	Sair com código 0 antes de acesso ao host, validação de dependências, setup de registry ou efeitos colaterais de runtime

6. Loop do Modo Watch

Quando --ivk-watch é passado, a execução é envolvida em um loop de watch:

Etapa	Componente	Ação
1	CLI	Detectar flag --ivk-watch (mutuamente exclusivo com --ivk-dry-run)
2	CLI	Executar comando inicial normalmente
3	Watch Engine	Configurar watchers de arquivo a partir de watch.patterns (ou fallback **/*)
4	Watch Engine	Aguardar mudanças em arquivos, debounce (padrão 500ms)
5	CLI	Re-executar comando
6	Watch Engine	Repetir a partir da etapa 4 até Ctrl+C

Tratamento de erros: Códigos de saída diferentes de zero do comando continuam o loop de watch. Erros de infraestrutura abortam o loop após 3 falhas consecutivas.

Pontos de Tratamento de Erros

Considerações de Performance

Fase	Duração Típica	Otimização
Inicialização	< 10ms	Config em cache após primeiro carregamento
Descoberta	10-100ms	Cache por requisição elimina varreduras duplicadas do sistema de arquivos
Resolução	< 1ms	Lookup simples
Execução	Variável	Depende do comando

Otimizações principais:

• Cache de descoberta por requisição: Um discoveryRequestCache anexado ao contexto da requisição memoriza resultados de DiscoverCommandSet, DiscoverAndValidateCommandSet e GetCommand. A cross-population garante que uma chamada DiscoverAndValidateCommandSet também satisfaz lookups downstream de DiscoverCommandSet, eliminando travessias redundantes do sistema de arquivos dentro de uma única invocação CLI.

Gargalos a observar:

• Muitos módulos nos includes configurados → descoberta mais lenta
• Invowkfiles grandes → parsing mais lento
• Pulls de imagem de container → pode levar minutos

Diagramas Relacionados

• Diagrama C4 de Container - Relacionamentos entre componentes
• Fluxograma de Seleção de Runtime - Como runtimes são escolhidos
• Fluxograma de Precedência de Descoberta - Como comandos são descobertos