Declarando Dependências

Dependências de módulos são declaradas no campo requires de invkmod.cue. Esta página cobre a sintaxe e opções disponíveis.

Sintaxe Básica

module: "com.example.mytools"
version: "1.0"

requires: [
    {
        git_url: "https://github.com/example/common.invkmod.git"
        version: "^1.0.0"
    },
]

Campos do Requirement

Campo	Obrigatório	Descrição
git_url	Sim	URL do repositório Git (HTTPS ou SSH)
version	Sim	Restrição de versão semântica
alias	Não	Namespace personalizado para comandos
path	Não	Subdiretório dentro do repositório

git_url

URL do repositório Git. Suporta formatos HTTPS e SSH. O repositório deve conter um módulo (um diretório .invkmod ou um invkmod.cue na raiz).

requires: [
    // HTTPS (works with public repos or GITHUB_TOKEN)
    {git_url: "https://github.com/user/tools.invkmod.git", version: "^1.0.0"},

    // SSH (requires SSH key in ~/.ssh/)
    {git_url: "git@github.com:user/tools.invkmod.git", version: "^1.0.0"},

    // GitLab
    {git_url: "https://gitlab.com/user/tools.invkmod.git", version: "^1.0.0"},

    // Self-hosted
    {git_url: "https://git.example.com/user/tools.invkmod.git", version: "^1.0.0"},
]

version

Restrição de versão semântica. O repositório precisa ter tags Git que correspondam à restrição.

Formatos de Restrição de Versão

Formato	Descrição	Corresponde
^1.2.3	Compatível (mesmo major)	>=1.2.3 <2.0.0
~1.2.3	Aproximado (mesmo minor)	>=1.2.3 <1.3.0
>=1.0.0	Maior ou igual	1.0.0, 1.5.0, 2.0.0, ...
>1.0.0	Maior que	1.0.1, 1.5.0, 2.0.0, ...
<2.0.0	Menor que	1.9.9, 1.0.0, 0.5.0, ...
<=2.0.0	Menor ou igual	2.0.0, 1.9.9, 1.0.0, ...
1.2.3	Versão exata	Apenas 1.2.3

Formatos de Tag de Versão

O Invowk aceita tags com ou sem o prefixo v:

• v1.2.3 e 1.2.3 são válidos
• Na resolução, ambos os formatos são tentados automaticamente

requires: [
    // Invowk tries both v1.0.0 and 1.0.0
    {git_url: "https://github.com/user/tools.invkmod.git", version: "^1.0.0"},
]

alias

Sobrescreva o namespace padrão para os comandos da dependência:

requires: [
    // Default namespace: common@1.2.3
    {git_url: "https://github.com/user/common.invkmod.git", version: "^1.0.0"},

    // Custom namespace: tools
    {
        git_url: "https://github.com/user/common.invkmod.git"
        version: "^1.0.0"
        alias: "tools"
    },
]

Uso com alias:

# Instead of: invowk cmd common@1.2.3 build
invowk cmd tools build

path

Para monorepos contendo múltiplos módulos, especifique o subdiretório:

requires: [
    {
        git_url: "https://github.com/user/monorepo.invkmod.git"
        version: "^1.0.0"
        path: "modules/cli-tools"
    },
    {
        git_url: "https://github.com/user/monorepo.invkmod.git"
        version: "^1.0.0"
        path: "modules/deploy-utils"
        alias: "deploy"
    },
]

Caminhos devem ser relativos e não podem conter .. ou caminhos absolutos.

Múltiplas Dependências

Declare várias dependências no array requires:

requires: [
    {
        git_url: "https://github.com/company/build-tools.invkmod.git"
        version: "^2.0.0"
        alias: "build"
    },
    {
        git_url: "https://github.com/company/deploy-tools.invkmod.git"
        version: "~1.5.0"
        alias: "deploy"
    },
    {
        git_url: "https://github.com/company/test-utils.invkmod.git"
        version: ">=1.0.0 <2.0.0"
    },
]

Autenticação

Chaves SSH

Para URLs SSH (git@...), o invowk usa chaves de ~/.ssh/:

1. ~/.ssh/id_ed25519 (preferida)
2. ~/.ssh/id_rsa
3. ~/.ssh/id_ecdsa

Tokens HTTPS

Para repositórios HTTPS privados, defina variáveis de ambiente:

# GitHub
export GITHUB_TOKEN=ghp_xxxx

# GitLab
export GITLAB_TOKEN=glpat-xxxx

# Generic (any Git server)
export GIT_TOKEN=your-token

Dependências Transitivas

Dependências podem declarar suas próprias dependências. Quando você sincroniza, o invowk resolve toda a árvore e registra no lock file:

com.example.app
├── common-tools@1.2.3
│   └── logging-utils@2.0.0
└── deploy-utils@1.5.0
    └── common-tools@1.2.3  (shared)

Detecção de Dependência Circular

O Invowk detecta e reporta dependências circulares:

Error: circular dependency detected: https://github.com/user/module-a.invkmod.git

Melhores Práticas

1. Use Caret para a Maioria das Dependências

// Good: allows patch and minor updates
{git_url: "...", version: "^1.0.0"}

// Too strict: no updates allowed
{git_url: "...", version: "1.0.0"}

2. Use Aliases para Namespaces Mais Limpos

{
    git_url: "https://github.com/company/company-internal-build-tools.invkmod.git"
    version: "^2.0.0"
    alias: "build"
}

3. Commite Seu Lock File

O arquivo invkmod.lock.cue deve ser commitado no controle de versão para builds reprodutíveis.

4. Atualize Regularmente

invowk module update

Referência de Schema

#ModuleRequirement: {
    git_url: string
    version: string
    alias?:  string
    path?:   string
}