Comandos e Namespaces

Os comandos do Invowk são nomeados diretamente em invowkfile.cue. Namespaces vêm dos módulos: comandos em um módulo são prefixados pelo ID do módulo definido em invowkmod.cue.

Nomes de Comandos

Nomes de comandos podem incluir espaços para criar hierarquias estilo subcomandos:

cmds: [
    {name: "test"},
    {name: "test unit"},
    {name: "test integration"},
    {name: "db migrate"},
    {name: "db seed"},
]

Regras de Nomenclatura de Comandos

Regra	Válido	Inválido
Deve começar com letra	build, Test	1build
Letras, números, espaços, hífens, underscores	test unit, build-all	build@all

Espaços são apenas organizacionais - não há relação especial pai-filho entre comandos.

Namespaces de Módulos

Os comandos de módulos são descobertos de todas as fontes e disponibilizados via seus nomes simples (o nome definido no invowkfile.cue).

// invowkmod.cue
module: "com.company.frontend"
version: "1.0.0"

// invowkfile.cue
cmds: [
    {name: "build"},
    {name: "test unit"},
]

Se estes forem os únicos comandos com esses nomes, eles se tornam disponíveis como:

• invowk cmd build
• invowk cmd test unit

Namespaces Transparentes

Quando os nomes dos comandos são únicos em todas as fontes, você pode omitir qualquer prefixo e usar apenas o nome simples do comando. O sistema de namespace transparente do Invowk resolve automaticamente comandos não ambíguos.

Se um nome de comando existir em múltiplas fontes, você deve desambiguar usando o prefixo @source:

• invowk cmd @invowkfile deploy (do invowkfile local)
• invowk cmd @com.company.frontend deploy (de um módulo específico)

Regras de Nomenclatura de IDs de Módulo

Regra	Válido	Inválido
Deve começar com letra	myproject, Project1	1project, _project
Apenas letras e números	myproject, v2	my-project, my_project
Pontos para aninhamento	my.project, a.b.c	my..project, .project, project.

Exemplos Válidos

module: "frontend"
module: "backend"
module: "my.project"
module: "com.company.tools"
module: "io.github.username.cli"

Exemplos Inválidos

module: "my-project"   // Hyphens not allowed
module: "my_project"   // Underscores not allowed
module: ".project"     // Can't start with dot
module: "project."     // Can't end with dot
module: "my..project"  // No consecutive dots
module: "123project"   // Must start with letter

Para módulos compartilhados, use nomenclatura RDNS (Reverse Domain Name System), como com.company.tools, para evitar colisões.

Descoberta de Comandos

O Invowk descobre comandos de múltiplas fontes em ordem de prioridade:

1. invowkfile do diretório atual (maior prioridade)
2. Módulos locais (*.invowkmod no diretório atual)
3. Includes configurados (caminhos de módulos do arquivo de configuração)
4. Diretório de comandos do usuário (~/.invowk/cmds/ — apenas *.invowkmod, não recursivo)

Ao listar comandos, você verá sua origem:

Available Commands
  (* = default runtime)

From invowkfile:
  build - Build the project [native*] (linux, macos, windows)

From tools.invowkmod:
  hello - A greeting [native*] (linux, macos)

Dependências de Comandos

Comandos podem depender de outros comandos. Use o nome completo como aparece no invowk cmd (prefixo do módulo quando aplicável):

cmds: [
    {
        name: "build"
        implementations: [...]
    },
    {
        name: "test"
        implementations: [...]
        depends_on: {
            cmds: [
                // Reference by command name in the same invowkfile
                {alternatives: ["build"]}
            ]
        }
    },
    {
        name: "release"
        implementations: [...]
        depends_on: {
            cmds: [
                // Module-prefixed commands for dependencies
                {alternatives: ["build"]},
                {alternatives: ["com.company.tools lint"]},
            ]
        }
    }
]

Por Que Namespaces Importam

1. Isolamento de namespace - Comandos de módulos ficam distintos entre toolkits compartilhados
2. Origem clara - O prefixo do módulo mostra de onde o comando vem
3. Organização lógica - IDs de módulo com pontos organizam comandos relacionados
4. Autocompletar - IDs de módulo criam limites naturais para completar com tab

Boas Práticas

• Projetos locais: mantenha nomes curtos e focados (sem prefixo).
• Módulos: use IDs RDNS como com.company.devtools.
• Evite IDs genéricos: prefira com.company.tools em vez de tools.

Próximos Passos

• Implementações - Aprenda sobre implementações de comandos específicas por plataforma
• Modos de Runtime - Entenda execução native, virtual e container