Pular para o conteúdo principal
Versão: 0.1.0

Criando Módulos

Aprenda como criar, estruturar e organizar módulos para seus comandos.

Criação Rápida​

Use module create para criar a estrutura de um novo módulo:

# Simple module
invowk module create mytools

# RDNS naming
invowk module create com.company.devtools

# In specific directory
invowk module create mytools --path /path/to/modules

# Custom module ID + description
invowk module create mytools --module-id com.company.tools --description "Shared tools"

# With scripts directory
invowk module create mytools --scripts

Estrutura Gerada​

Módulo básico:

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

Com --scripts:

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

Metadados do Módulo (invowkmod.cue)​

O invowkmod.cue gerado contém identidade e dependências do módulo:

module: "mytools"
version: "1.0.0"
description: "Commands for mytools"

// Uncomment to add dependencies:
// requires: [
//     {
//         git_url: "https://github.com/example/utils.invowkmod.git"
//         version: "^1.0.0"
//     },
// ]

Invowkfile Template​

O invowkfile.cue gerado contém apenas comandos:

cmds: [
    {
        name: "hello"
        description: "Say hello"
        implementations: [
            {
                script: """
                    echo "Hello from mytools!"
                    """
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
            }
        ]
    }
]

Criação Manual​

Você também pode criar módulos manualmente:

mkdir mytools.invowkmod
touch mytools.invowkmod/invowkmod.cue
touch mytools.invowkmod/invowkfile.cue

Adicionando Scripts​

Inline vs Externo​

Escolha baseado na complexidade:

cmds: [
    // Simple: inline script
    {
        name: "quick"
        implementations: [{
            script: "echo 'Quick task'"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
        }]
    },

    // Complex: external script
    {
        name: "complex"
        implementations: [{
            script: "scripts/complex-task.sh"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }]
    }
]

Organização de Scripts​

mytools.invowkmod/
├── invowkmod.cue
├── invowkfile.cue
└── scripts/
    ├── build.sh           # Main scripts
    ├── deploy.sh
    ├── test.sh
    └── lib/               # Shared utilities
        ├── logging.sh
        └── validation.sh

Caminhos de Script​

Sempre use barras normais:

// Good
script: "scripts/build.sh"
script: "scripts/lib/logging.sh"

// Bad - will fail on some platforms
script: "scripts\\build.sh"

// Bad - escapes module directory
script: "../outside.sh"

Arquivos de Environment​

Inclua arquivos .env no seu módulo:

mytools.invowkmod/
├── invowkmod.cue
├── invowkfile.cue
├── .env                   # Default config
├── .env.example           # Template for users
└── scripts/

Referencie-os:

env: {
    files: [".env"]
}

Documentação​

Inclua um README para usuários:

mytools.invowkmod/
├── invowkmod.cue
├── invowkfile.cue
├── README.md              # Usage instructions
├── CHANGELOG.md           # Version history
└── scripts/

Exemplos do Mundo Real​

Módulo de Build Tools​

com.company.buildtools.invowkmod/
├── invowkmod.cue
├── invowkfile.cue
├── scripts/
│   ├── build-go.sh
│   ├── build-node.sh
│   └── build-python.sh
├── templates/
│   ├── Dockerfile.go
│   ├── Dockerfile.node
│   └── Dockerfile.python
└── README.md
cmds: [
    {
        name: "go"
        description: "Build Go project"
        implementations: [{
            script: "scripts/build-go.sh"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }]
    },
    {
        name: "node"
        description: "Build Node.js project"
        implementations: [{
            script: "scripts/build-node.sh"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }]
    },
    {
        name: "python"
        description: "Build Python project"
        implementations: [{
            script: "scripts/build-python.sh"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }]
    }
]

Módulo DevOps​

org.devops.k8s.invowkmod/
├── invowkmod.cue
├── invowkfile.cue
├── scripts/
│   ├── deploy.sh
│   ├── rollback.sh
│   └── status.sh
├── manifests/
│   ├── deployment.yaml
│   └── service.yaml
└── .env.example

Melhores Práticas​

  1. Use nomenclatura RDNS: Previne conflitos com outros módulos
  2. Mantenha scripts focados: Uma tarefa por script
  3. Inclua documentação: README com exemplos de uso
  4. Versione seu módulo: Defina a versão em invowkmod.cue
  5. Apenas barras normais: Compatibilidade multiplataforma
  6. Valide antes de compartilhar: Execute module validate --deep

Validando Seu Módulo​

Antes de compartilhar, valide:

invowk module validate mytools.invowkmod --deep

Veja Validando para detalhes.

Próximos Passos​