Visão Geral de Módulos

Alpha — O Formato de Módulo Pode Mudar

O formato e estrutura de módulos ainda estão sendo finalizados. Embora nosso objetivo seja manter compatibilidade retroativa, mudanças incompatíveis podem ocorrer antes do release 1.0. Se você está distribuindo módulos externamente, esteja preparado para atualizá-los ao fazer upgrade do Invowk™.

Módulos são pastas autocontidas que agrupam metadados invowkmod.cue com comandos opcionais em invowkfile.cue e quaisquer arquivos de script que eles referenciam. Eles são perfeitos para compartilhar comandos, criar toolkits reutilizáveis e distribuir automação entre equipes.

O que é um Módulo?

Um módulo é um diretório com o sufixo .invowkmod:

mytools.invowkmod/
├── invowkmod.cue          # Required: module metadata
├── invowkfile.cue          # Optional: command definitions
├── scripts/              # Optional: script files
│   ├── build.sh
│   └── deploy.sh
└── templates/             # Optional: other resources
    └── config.yaml

Por que Usar Módulos?

• Portabilidade: Compartilhe um conjunto completo de comandos como uma única pasta
• Autocontido: Scripts ficam agrupados no módulo
• Multiplataforma: Caminhos com barra funcionam em qualquer lugar
• Isolamento de namespace: Nomenclatura RDNS previne conflitos
• Fácil distribuição: Compacte, compartilhe, descompacte

Início Rápido

Criar um Módulo

invowk module create mytools

Cria:

mytools.invowkmod/
├── invowkmod.cue
└── invowkfile.cue

Usar o Módulo

Módulos são descobertos automaticamente de:

1. Diretório atual (invowkfile e módulos locais)
2. Entradas de includes configuradas
3. ~/.invowk/cmds/ (módulos do usuário — apenas *.invowkmod, não recursivo)

# List commands (module commands appear automatically)
invowk cmd

# Run a module command
invowk cmd mytools hello

Compartilhar o Módulo

# Create a zip archive
invowk module archive mytools.invowkmod

# Share the zip file
# Recipients import with:
invowk module import mytools.invowkmod.zip

Estrutura de Módulo

Arquivos Obrigatórios

• invowkmod.cue: Metadados do módulo (nome, versão, dependências)

Conteúdo Opcional

• invowkfile.cue: Definições de comandos (omita para módulos apenas de biblioteca)
• Scripts: Shell scripts, arquivos Python, etc.
• Templates: Templates de configuração
• Dados: Quaisquer arquivos de suporte

Exemplo de Estrutura

com.example.devtools.invowkmod/
├── invowkmod.cue
├── invowkfile.cue
├── scripts/
│   ├── build.sh
│   ├── deploy.sh
│   └── utils/
│       └── helpers.sh
├── templates/
│   ├── Dockerfile.tmpl
│   └── config.yaml.tmpl
└── README.md

Nomenclatura de Módulo

Nomes de pasta de módulo seguem estas regras:

Regra	Válido	Inválido
Terminar com .invowkmod	mytools.invowkmod	mytools
Começar com letra	mytools.invowkmod	123tools.invowkmod
Alfanumérico + pontos	com.example.invowkmod	my-tools.invowkmod

Nomenclatura RDNS

Recomendada para módulos compartilhados:

com.company.projectname.invowkmod
io.github.username.toolkit.invowkmod
org.opensource.utilities.invowkmod

Caminhos de Script

Referencie scripts relativos à raiz do módulo com barras normais:

// Inside mytools.invowkmod/invowkfile.cue
cmds: [
    {
        name: "build"
        implementations: [{
            script: "scripts/build.sh"  // Relative to module root
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }]
    },
    {
        name: "deploy"
        implementations: [{
            script: "scripts/utils/helpers.sh"  // Nested path
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }]
    }
]

Importante:

• Sempre use barras normais (/)
• Caminhos são relativos à raiz do módulo
• Caminhos absolutos não são permitidos
• Não é possível escapar do diretório do módulo (../ é inválido)

Comandos de Módulo

Comando	Descrição
invowk module create	Criar um novo módulo
invowk module list	Listar módulos descobertos
invowk module archive	Criar arquivo zip
invowk module import	Instalar de zip/URL
invowk module vendor	Fazer vendor de dependências de módulo localmente
invowk module add	Adicionar uma dependência de módulo (resolve, armazena em cache, atualiza lock file e invowkmod.cue)
invowk module remove	Remover uma dependência de módulo (atualiza lock file e invowkmod.cue)
invowk module sync	Sincronizar dependências de invowkmod.cue para lock file
invowk module update	Atualizar dependências de módulo para as versões mais recentes compatíveis
invowk module deps	Exibir árvore de dependências

Descoberta

Módulos são descobertos dessas localizações:

1. invowkfile do diretório atual (maior prioridade)
2. Módulos locais (*.invowkmod no diretório atual)
3. Includes configurados (caminhos de módulos da configuração)
4. Diretório de comandos do usuário (~/.invowk/cmds/ — apenas *.invowkmod, não recursivo)

Comandos aparecem em invowk cmd com sua origem:

Available Commands

From invowkfile:
  build - Build the project [native*]

From com.example.utilities.invowkmod:
  hello - Greeting [native*]

Próximos Passos

• Criando Módulos - Criar estrutura e organizar módulos
• Validando - Garantir integridade do módulo
• Distribuindo - Compartilhar módulos com outros
• Dependências de Módulos - Usar outros módulos no seu módulo