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 invkmod.cue com comandos opcionais em invkfile.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 .invkmod:

mytools.invkmod/
├── invkmod.cue          # Required: module metadata
├── invkfile.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.invkmod/
├── invkmod.cue
└── invkfile.cue

Usar o Módulo

Módulos são descobertos automaticamente de:

1. Diretório atual (invkfile e módulos locais)
2. ~/.invowk/cmds/ (comandos do usuário)
3. Caminhos de busca configurados

# 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.invkmod

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

Estrutura de Módulo

Arquivos Obrigatórios

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

Conteúdo Opcional

• invkfile.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.invkmod/
├── invkmod.cue
├── invkfile.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 .invkmod	mytools.invkmod	mytools
Começar com letra	mytools.invkmod	123tools.invkmod
Alfanumérico + pontos	com.example.invkmod	my-tools.invkmod

Nomenclatura RDNS

Recomendada para módulos compartilhados:

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

Caminhos de Script

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

// Inside mytools.invkmod/invkfile.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 validate	Validar estrutura do módulo
invowk module list	Listar módulos descobertos
invowk module archive	Criar arquivo zip
invowk module import	Instalar de zip/URL

Descoberta

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

1. invkfile do diretório atual (maior prioridade)
2. Módulos locais (*.invkmod no diretório atual)
3. Comandos do usuário (~/.invowk/cmds/)
4. Caminhos de busca (da configuração)

Comandos aparecem em invowk cmd com sua origem:

Available Commands

From current directory:
  mytools build - Build the project [native*]

From user commands (~/.invowk/cmds):
  com.example.utilities 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