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

Referência de Schema do Invowkmod

:::warning Alpha — Schema Pode Mudar O schema do invowkmod ainda está evoluindo. Campos, tipos e regras de validação podem mudar entre releases enquanto estabilizamos o formato. Sempre verifique o changelog ao fazer upgrade. :::

Referência completa para invowkmod.cue, o arquivo de metadados do módulo. Metadados são validados como struct fechado, então campos desconhecidos geram erro de validação.

Estrutura Raiz​

Todo módulo deve incluir um arquivo invowkmod.cue com esta estrutura:

#Invowkmod: {
    module:       string               // Required - module identifier
    version:      string               // Required - semver version (e.g., "1.0.0")
    description?: string               // Optional - module description
    author?:      string               // Optional - author or maintainer
    license?:     string               // Optional - SPDX license identifier
    repository?:  string               // Optional - canonical source URL
    requires?:    [...#ModuleRequirement] // Optional - dependencies
}

module​

Tipo: string (padrão: ^[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z][a-zA-Z0-9]*)*$) Obrigatório: Sim

O identificador do módulo. Diretórios de módulos instalados localmente usam este valor como <module-id>.invowkmod. Para subpaths explícitos de dependências, o basename do diretório selecionado deve corresponder a este prefixo antes de .invowkmod. Para uma origem na raiz de um repositório Git, o basename do repositório não precisa corresponder.

module: "mytools"
module: "com.company.devtools"
module: "io.github.username.cli"

version​

Tipo: string (padrão: ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*)?$) Obrigatório: Sim

Versão do módulo em formato semver (ex: "1.0.0", "2.1.0-beta.1").

description​

Tipo: string Obrigatório: Não

Um resumo curto do propósito do módulo.

author​

Tipo: string Obrigatório: Não

Autor ou mantenedor do módulo (texto livre, tipicamente "Nome <email>" ou nome da organização).

license​

Tipo: string Obrigatório: Não

Licença do módulo usando um identificador SPDX (ex: "MIT", "Apache-2.0", "MPL-2.0").

repository​

Tipo: string (padrão: ^(https://|git@|ssh://)) Obrigatório: Não

URL canônica de origem deste módulo. Apenas esquemas https://, git@ e ssh:// são aceitos.

requires​

Tipo: [...#ModuleRequirement] Obrigatório: Não

Lista de dependências de módulos em repositórios Git.

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

ModuleRequirement​

Define uma entrada de dependência:

#ModuleRequirement: {
    git_url: string
    version: string
    alias?:  string
    path?:   string  // Relative subdirectory; traversal is rejected after decode
}

git_url​

Tipo: string Obrigatório: Sim

URL do repositório Git. Formas aceitas: HTTPS (https://...), SSH shorthand (git@...) ou URI SSH (ssh://...). O basename do repositório não precisa terminar em .invowkmod.

Quando path é omitido, a raiz do repositório buscado deve conter invowkmod.cue e invowkfile.cue. Módulos filhos não são selecionados automaticamente; declare path em monorepos.

version​

Tipo: string Obrigatório: Sim

Restrição de versão semântica usada para resolver uma tag Git. Os formatos aceitos são uma versão semântica simples ou um operador entre ^, ~, >, >=, <, <= ou = seguido por uma versão semântica. O valor da restrição não pode usar prefixo v, lixo no final ou ranges compostos como >=1.0.0 <2.0.0.

alias​

Tipo: string Obrigatório: Não

Sobrescreve o ID de origem de comando padrão para esta dependência. Aliases usam regras de command source ID: devem começar com uma letra e podem conter letras, dígitos, ., _ ou -.

path​

Tipo: string Obrigatório: Não

Subdiretório dentro do repositório que contém o módulo. Deve ser relativo e apontar diretamente para um diretório cujo basename termina em .invowkmod. O prefixo do basename deve corresponder ao valor module do módulo selecionado. Nomes comuns de segmento com pontos consecutivos são permitidos, mas segmentos de diretório pai como .., caminhos absolutos, caminhos com drive e caminhos UNC/enraizados são rejeitados depois que o Invowk normaliza os separadores.