MechaOnion.Tool 0.1.0

dotnet tool install --global MechaOnion.Tool --version 0.1.0
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local MechaOnion.Tool --version 0.1.0
                    
This package contains a .NET tool you can call from the shell/command line.
#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 ef local;
  • 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-run não escreve; --force é obrigatório para sobrescrever destino não vazio.
  • O projeto gerado usa user-secrets/variáveis de ambiente e .gitignore para .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

  • NU1903 no 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 ef indisponível: execute dotnet tool restore na raiz do projeto gerado; o manifesto .config/dotnet-tools.json fixa o dotnet-ef.
  • PostgreSQL indisponível: a geração continua; a migração fica criada e o --apply pode ser executado depois com o comando impresso pelo tool.
  • 42P07: relation "..." already exists ao executar o host: o banco já tem o schema de uma geração anterior. Ao regenerar com new --force, a nova migração InitialCreate recebe outro id e o EF tenta recriar as tabelas. Recrie o banco/schema e rode novamente: DROP SCHEMA public CASCADE; CREATE SCHEMA public; ou dotnet 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/logs e .mechaonion/backup.
  • dotnet format no ambiente: se o MSBuild BuildHost falhar localmente, rode dotnet format MechaOnion.Tool.csproj --verify-no-changes no 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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.