Comandos e Namespaces

Os comandos do Invowk são nomeados diretamente em invkfile.cue. Namespaces vêm dos módulos: comandos em um módulo são prefixados pelo ID do módulo definido em invkmod.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

Comandos de módulos são namespaced pelo campo module em invkmod.cue:

// invkmod.cue
module: "com.company.frontend"

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

Esses comandos se tornam:

• invowk cmd com.company.frontend build
• invowk cmd com.company.frontend test unit

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. Diretório atual (maior prioridade)
2. Diretório de comandos do usuário (~/.invowk/cmds/)
3. Caminhos de busca configurados (do arquivo de configuração)

Ao listar comandos, você verá sua origem:

Available Commands
  (* = default runtime)

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

From user commands (~/.invowk/cmds):
  com.example.tools 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 --list (prefixo do módulo quando aplicável):

cmds: [
    {
        name: "build"
        implementations: [...]
    },
    {
        name: "test"
        implementations: [...]
        depends_on: {
            cmds: [
                // Reference by command name in the same invkfile
                {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