Declarando Dependências

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

Sintaxe Básica

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

requires: [
    {
        git_url: "https://github.com/example/common.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	ID de origem de comando 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 nome do repositório é apenas a localização da origem; ele não precisa terminar em .invowkmod e não define a identidade do módulo.

Quando path é omitido, a raiz do repositório deve conter invowkmod.cue e invowkfile.cue. Se o módulo fica em um diretório filho, declare path explicitamente.

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

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

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

    // Self-hosted
    {git_url: "https://git.example.com/user/tools.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 resolve automaticamente tags Git com ou sem o prefixo v — tanto tags v1.2.3 quanto 1.2.3 são encontradas durante a busca.

No entanto, o valor da restrição version no invowkmod.cue não deve incluir o prefixo v. Escreva version: "^1.2.3", não version: "^v1.2.3".

Cada requirement aceita uma única expressão de restrição. Use version: ">=1.0.0" ou version: "<=2.0.0" como um limite único; ranges compostos como ">=1.0.0 <2.0.0" são rejeitados.

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

alias

Sobrescreva o ID de origem de comando padrão para os comandos da dependência:

requires: [
    // Default command source ID: io.example.common
    {git_url: "https://github.com/user/common.git", version: "^1.0.0"},

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

O ID de origem de comando padrão vem de invowkmod.cue: module, não do basename do repositório Git. Um alias muda apenas o namespace de comando usado para execução e desambiguação; ele não muda a identidade canônica do módulo, diretório de cache, diretório de vendor ou module_id do lock.

Uso com alias:

# Instead of: invowk cmd common 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.git"
        version: "^1.0.0"
        path: "modules/io.example.cli.invowkmod"
    },
    {
        git_url: "https://github.com/user/monorepo.git"
        version: "^1.0.0"
        path: "modules/io.example.deploy.invowkmod"
        alias: "deploy"
    },
]

Caminhos devem ser relativos, não podem conter .. ou caminhos absolutos, e devem apontar diretamente para um diretório cujo basename termina em .invowkmod. Para subpaths explícitos, o prefixo do basename deve corresponder ao valor module do módulo selecionado. Por exemplo, modules/io.example.cli.invowkmod deve conter module: "io.example.cli".

Dependências sincronizadas e vendorizadas são materializadas localmente como <module-id>.invowkmod, mesmo quando o repositório de origem tem um nome comum como tools.git.

Múltiplas Dependências

Declare várias dependências no array requires:

requires: [
    {
        git_url: "https://github.com/company/build-tools.git"
        version: "^2.0.0"
        alias: "build"
    },
    {
        git_url: "https://github.com/company/deploy-tools.git"
        version: "~1.5.0"
        alias: "deploy"
    },
    {
        git_url: "https://github.com/company/test-utils.git"
        version: ">=1.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

O Invowk usa um modelo de dependências explícitas (como Go modules): todo módulo na árvore de dependências deve ser declarado no invowkmod.cue raiz. Se o módulo A requer o módulo B, e B requer C, então C também deve ser declarado no seu invowkmod.cue.

• invowk module sync falhará com erros acionáveis listando dependências transitivas faltantes.
• invowk module tidy verifica os módulos resolvidos e adiciona automaticamente dependências transitivas faltantes ao seu invowkmod.cue.

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.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.git"
    version: "^2.0.0"
    alias: "build"
}

3. Commite Seu Lock File

O arquivo invowkmod.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  // Relative subdirectory; traversal is rejected after decode
}