MechaOnion.Tool
0.1.0
dotnet tool install --global MechaOnion.Tool --version 0.1.0
dotnet new tool-manifest
dotnet tool install --local MechaOnion.Tool --version 0.1.0
#tool dotnet:?package=MechaOnion.Tool&version=0.1.0
nuke :add-package MechaOnion.Tool --version 0.1.0
MechaOnion.Tool
mechaonion é um .NET global tool que gera projetos e módulos MechaOnion seguindo a estrutura e as
convenções do Cordel-Lms. O projeto nasce com host ASP.NET Core, front-end Blazor WebAssembly,
autenticação por tenant, área administrativa, CRUD de exemplo, migrações e documentação para agentes.
- Package:
MechaOnion.Tool(nuget.org) - Comando:
mechaonion - Licença: GPL-3.0-only (o projeto gerado não impõe licença ao usuário)
Requisitos
- SDK .NET 10
- Acesso ao feed NuGet (
nuget.org) - PostgreSQL 17 e Docker para executar o projeto gerado (o tool em si não exige banco)
Verifique o ambiente com mechaonion doctor antes de gerar.
Instalação
dotnet tool install --global MechaOnion.Tool
mechaonion --version
mechaonion doctor
Atualização:
dotnet tool update --global MechaOnion.Tool
Instalação local (sem afetar o PATH global):
dotnet tool install --tool-path ./.tools MechaOnion.Tool
./.tools/mechaonion --version
Comandos
mechaonion --version
Mostra a versão do tool e a versão MechaOnion suportada pela matriz de compatibilidade.
mechaonion --version
mechaonion doctor
Diagnostica os pré-requisitos e retorna 3 quando há erro bloqueante. Cada verificação informa
ok, warning, error ou skipped com mensagem e dica acionáveis:
- SDK .NET 10;
- acesso ao feed NuGet;
- disponibilidade do
dotnet eflocal; - Docker (apenas aviso, não bloqueia);
- permissão de escrita no diretório de destino;
- conectividade com PostgreSQL, quando houver
MECHAONION_DB_CONNECTION.
mechaonion doctor
mechaonion doctor --json
mechaonion doctor --verbose
O doctor não executa restore, não cria arquivos de projeto e não derruba o processo em falha de
rede/NuGet. O arquivo transitório de sondagem de escrita é removido no mesmo check.
mechaonion new
Cria um projeto completo. O wizard pergunta apenas os dados ausentes; com --yes, usa defaults e
falha se algum dado obrigatório não for informado.
# Planeje sem escrever no disco
mechaonion new --name Sample --prefix Sample --dry-run --json
# Gere com defaults
mechaonion new --name Sample --prefix Sample --admin-password "$MECHAONION_ADMIN_PASSWORD" --yes
# Escolha destino, tenant e administrador; a senha/connection string nunca vão para arquivos
mechaonion new \
--name Sample --prefix Sample --output ./Sample \
--tenant-slug sample --admin-login admin --admin-email admin@sample.local \
--admin-password "$MECHAONION_ADMIN_PASSWORD" \
--db "Host=localhost;Database=sample;Username=sample;Password=$MECHAONION_DB_PASSWORD" \
--yes
Ao final, o tool executa restore, build e cria a migração InitialCreate, imprimindo o resumo e
os próximos passos. Falhas de geração publicam a árvore de forma atômica: nenhum diretório parcial
fica no destino.
A connection string informada no wizard ou em --db é validada e normalizada para o formato
Host=...;Port=...;Database=...;Username=...;Password=... e gravada em user-secrets do host
gerado (nunca em appsettings.Development.json, que é versionado). Em Development o host lê, nesta
ordem: user-secrets → appsettings.Development.json → appsettings.json → variáveis de ambiente.
Para alterar o valor depois, use dotnet user-secrets set "DatabaseSettings:ConnectionString" "..." --project <Prefixo>.Api; o mechaonion doctor valida a connection string efetiva.
mechaonion add module
Adiciona um CRUD de entidade raiz a um projeto criado por mechaonion new (marcador
.mechaonion/project.json). O wizard pergunta módulo, entidade, plural/rota, menu, permissão e
campos; o modo não interativo aceita --field nome:tipo:obrigatório:max:único:default.
Tipos do v1: shortText, longText, int, decimal, bool, date, datetime, guid e
enum. A comparação é case-insensitive (dateTime também é aceito).
# Prévia sem escrever
mechaonion add module --module Billing --entity Invoice \
--field Number:shortText:true:40:true --field Amount:decimal:true --dry-run
# Geração + migração AddBilling
mechaonion add module --module Billing --entity Invoice \
--field Number:shortText:true:40:true --field Amount:decimal:true --yes
# Geração + aplicação da migração (quando o banco estiver acessível)
mechaonion add module --module Billing --entity Invoice \
--field Number:shortText:true:40:true --field Amount:decimal:true --yes --apply
A migração é sempre gerada. Em falha de geração, build ou scaffold, o tool restaura marcador,
registros, .slnx e .csproj, remove os arquivos do módulo e descarta a migração criada, mantendo
o backup em .mechaonion/backup para diagnóstico. Se o database update falhar, arquivos e
migração permanecem; o tool imprime o comando de correção e grava o log em .mechaonion/logs.
Colisões de módulo/entidade retornam 2 antes de qualquer escrita.
O código gerado contém pontos de extensão // MECHAONION: fine-tune <motivo> e não inventa regras
de negócio.
mechaonion agent-guide
Imprime o manual consumível por agentes/LLMs com comandos, flags, mapa de arquivos, convenções,
exemplos, troubleshooting e códigos de saída. O mesmo conteúdo acompanha o projeto gerado em
docs/agent-guide.md, referenciado por AGENTS.md e llms.txt, com o mapa canônico em
.mechaonion/project.json.
mechaonion agent-guide
mechaonion agent-guide --format json
Flags
| Flag | Comandos | Descrição |
|---|---|---|
--name, --prefix, --output |
new |
Nome, namespace raiz e diretório do projeto. |
--db |
new |
Connection string transitória do PostgreSQL; prefira MECHAONION_DB_CONNECTION (a flag fica no histórico). |
--tenant-slug, --admin-login, --admin-email, --admin-password |
new |
Dados do tenant/administrador inicial; prefira MECHAONION_ADMIN_PASSWORD para a senha. |
--mechaonion-version |
new |
Fixa uma versão da matriz de compatibilidade. |
--no-sample, --no-compose |
new |
Omite o módulo de exemplo ou o docker-compose/.env.example. |
--module, --entity, --plural, --route, --menu, --permission-prefix, --field |
add module |
Dados do módulo e campos. |
--dry-run |
new, add module |
Mostra o plano completo sem escrever no disco. |
--force |
new |
Substitui um diretório de destino não vazio. |
--apply |
add module |
Aplica a migração com dotnet ef database update. |
--yes |
new, add module |
Modo não interativo com defaults. |
--json |
todos | Envelope JSON estável (success, command, code, files, warnings, errors, checks, version). |
--verbose |
todos | Inclui detalhes de execução. |
--no-color |
todos | Desabilita cores. |
Códigos de saída
| Código | Significado |
|---|---|
| 0 | Sucesso |
| 2 | Entrada inválida (comando, opção, nome, caminho ou colisão) |
| 3 | Ambiente inválido (SDK, NuGet, dotnet ef, Docker opcional ou permissão) |
| 4 | Falha durante a geração de arquivos |
| 5 | Falha em migração, restore ou build |
Segurança
- O tool não coleta telemetria e não referencia SDKs de analytics.
- Senhas, connection strings, tokens Bearer e JWT são mascarados em stdout, stderr, JSON e logs.
- Toda escrita fica dentro do destino, com rejeição de
.., caminho absoluto e symlink. --dry-runnão escreve;--forceé obrigatório para sobrescrever destino não vazio.- O projeto gerado usa user-secrets/variáveis de ambiente e
.gitignorepara.env,bin/,obj/,.mechaonion/logs/e.mechaonion/backup/. Segredos nunca entram em.mechaonion/project.json. - O pacote não inclui fontes de teste,
bin/,obj/nem.git/.
Desempenho
Metas de referência no CI/local: geração de new ≤ 60 s, add module ≤ 30 s e build do projeto
gerado ≤ 5 min (além de restore/NuGet e banco). O CI executa a suíte em Linux, macOS e Windows.
Smoke manual com PostgreSQL real
O fluxo de --apply é opt-in e não roda na suíte padrão. Para validar contra um PostgreSQL real:
docker compose up -d
dotnet tool restore
dotnet ef database update --project Sample.Api --startup-project Sample.Api --context GlobalDbContext
mechaonion add module --module Billing --entity Invoice --field Number:shortText:true:40:true --yes --apply
dotnet ef migrations list --project Sample.Api --startup-project Sample.Api --context GlobalDbContext
Para habilitar os testes opt-in do próprio tool:
export MECHAONION_TEST_DB_CONNECTION="Host=localhost;Database=mechaonion_tests;Username=postgres;Password=<password>"
dotnet test tests/MechaOnion.Tool.Tests/MechaOnion.Tool.Tests.csproj
Troubleshooting
NU1903no projeto gerado: é um advisory transitivo de uma dependência publicada pela MechaOnion/Cordel e não é controlado pelo usuário. O build do projeto gerado não trata warnings como erro; acompanhe a atualização da matriz e do pacote MechaOnion.dotnet efindisponível: executedotnet tool restorena raiz do projeto gerado; o manifesto.config/dotnet-tools.jsonfixa odotnet-ef.- PostgreSQL indisponível: a geração continua; a migração fica criada e o
--applypode ser executado depois com o comando impresso pelo tool. 42P07: relation "..." already existsao executar o host: o banco já tem o schema de uma geração anterior. Ao regenerar comnew --force, a nova migraçãoInitialCreaterecebe outro id e o EF tenta recriar as tabelas. Recrie o banco/schema e rode novamente:DROP SCHEMA public CASCADE; CREATE SCHEMA public;oudotnet ef database drop --force --project <Prefixo>.Api. O host gerado detecta esse cenário e imprime a instrução em vez do erro cru do Npgsql.- Falha de geração: o destino é limpo (ou restaurado no
add module); consulte.mechaonion/logse.mechaonion/backup. dotnet formatno ambiente: se o MSBuild BuildHost falhar localmente, rodedotnet format MechaOnion.Tool.csproj --verify-no-changesno CI; o workflow já executa o check.
Desenvolvimento
dotnet restore MechaOnion.Tool.csproj
dotnet build MechaOnion.Tool.csproj -warnaserror
dotnet test tests/MechaOnion.Tool.Tests/MechaOnion.Tool.Tests.csproj
dotnet pack MechaOnion.Tool.csproj -c Release -o ./artifacts
O CI em .github/workflows/ci.yml (na raiz do repositório) roda restore, format, build com warnings
como erro, testes, pack, instalação local e smoke (--version, doctor, agent-guide) em
ubuntu-latest, macos-latest e windows-latest.
Publicação (NuGet)
A versão publicada vem da tag v* (ou do input manual do workflow). Antes de publicar, confirme que o
PackageId MechaOnion.Tool está livre/disponível na sua conta e configure o secret
NUGET_API_KEY em Settings → Secrets and variables → Actions do repositório.
Fluxo automatizado:
git tag v0.1.1
git push origin v0.1.1
O workflow .github/workflows/publish.yml roda restore, build, testes, pack com a versão da tag e
envia o pacote para https://api.nuget.org/v3/index.json (--skip-duplicate torna reexecuções
idempotentes). Também é possível disparar manualmente em Actions → publish → Run workflow informando
a versão.
Publicação manual:
# 1. Ajuste <Version> no MechaOnion.Tool.csproj (ou use -p:Version=x.y.z)
dotnet pack MechaOnion.Tool.csproj -c Release -o ./artifacts
# 2. Valide o pacote antes de enviar
dotnet tool install --global --add-source ./artifacts MechaOnion.Tool --version x.y.z
mechaonion --version
# 3. Envie para o nuget.org
dotnet nuget push ./artifacts/MechaOnion.Tool.x.y.z.nupkg \
--api-key "$NUGET_API_KEY" \
--source https://api.nuget.org/v3/index.json
O NuGet não permite republicar a mesma versão; cada envio exige uma versão nova. A propagação no
nuget.org pode levar alguns minutos antes de dotnet tool install --global MechaOnion.Tool enxergar
a nova versão.
Licença
GPL-3.0-only. Consulte LICENSE na raiz do repositório.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0 | 92 | 11/13/2026 |
0.1.0: geração de projetos e módulos, doctor completo, JSON estável, atomicidade, sem telemetria e CI Linux/macOS/Windows.