@matizze/prumo-cli 0.0.0-stage → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. package/README.md +121 -2
  2. package/dist/api.d.ts +10 -0
  3. package/dist/api.js +9 -0
  4. package/dist/args.d.ts +11 -0
  5. package/dist/args.js +61 -0
  6. package/dist/bin.d.ts +2 -0
  7. package/dist/bin.js +11 -0
  8. package/dist/codemod/add-route.d.ts +66 -0
  9. package/dist/codemod/add-route.js +435 -0
  10. package/dist/codemod/edit.d.ts +35 -0
  11. package/dist/codemod/edit.js +51 -0
  12. package/dist/codemod/index.d.ts +8 -0
  13. package/dist/codemod/index.js +8 -0
  14. package/dist/codemod/merge-barrel.d.ts +9 -0
  15. package/dist/codemod/merge-barrel.js +49 -0
  16. package/dist/codemod/messages.d.ts +11 -0
  17. package/dist/codemod/messages.js +46 -0
  18. package/dist/codemod/names.d.ts +62 -0
  19. package/dist/codemod/names.js +204 -0
  20. package/dist/codemod/plan.d.ts +45 -0
  21. package/dist/codemod/plan.js +147 -0
  22. package/dist/codemod/register-domain.d.ts +51 -0
  23. package/dist/codemod/register-domain.js +237 -0
  24. package/dist/codemod/register-messages.d.ts +11 -0
  25. package/dist/codemod/register-messages.js +112 -0
  26. package/dist/codemod/route-elements.d.ts +25 -0
  27. package/dist/codemod/route-elements.js +72 -0
  28. package/dist/commands/check.d.ts +16 -0
  29. package/dist/commands/check.js +47 -0
  30. package/dist/commands/doctor.d.ts +20 -0
  31. package/dist/commands/doctor.js +87 -0
  32. package/dist/commands/make-component.d.ts +33 -0
  33. package/dist/commands/make-component.js +85 -0
  34. package/dist/commands/make-domain.d.ts +30 -0
  35. package/dist/commands/make-domain.js +83 -0
  36. package/dist/commands/make-page.d.ts +30 -0
  37. package/dist/commands/make-page.js +73 -0
  38. package/dist/commands/new.d.ts +33 -0
  39. package/dist/commands/new.js +184 -0
  40. package/dist/commands/shared.d.ts +43 -0
  41. package/dist/commands/shared.js +83 -0
  42. package/dist/describe.d.ts +63 -0
  43. package/dist/describe.js +134 -0
  44. package/dist/doctor/checks.d.ts +35 -0
  45. package/dist/doctor/checks.js +283 -0
  46. package/dist/doctor/ranges.d.ts +16 -0
  47. package/dist/doctor/ranges.js +27 -0
  48. package/dist/doctor/versions.d.ts +33 -0
  49. package/dist/doctor/versions.js +44 -0
  50. package/dist/errors.d.ts +12 -0
  51. package/dist/errors.js +19 -0
  52. package/dist/generate/app.d.ts +29 -0
  53. package/dist/generate/app.js +137 -0
  54. package/dist/generate/component.d.ts +36 -0
  55. package/dist/generate/component.js +48 -0
  56. package/dist/generate/domain.d.ts +31 -0
  57. package/dist/generate/domain.js +63 -0
  58. package/dist/generate/page.d.ts +45 -0
  59. package/dist/generate/page.js +100 -0
  60. package/dist/help.d.ts +19 -0
  61. package/dist/help.js +97 -0
  62. package/dist/in-process.d.ts +26 -0
  63. package/dist/in-process.js +23 -0
  64. package/dist/index.d.ts +9 -0
  65. package/dist/index.js +9 -0
  66. package/dist/new/name.d.ts +7 -0
  67. package/dist/new/name.js +24 -0
  68. package/dist/new/packages.d.ts +6 -0
  69. package/dist/new/packages.js +40 -0
  70. package/dist/new/versions.d.ts +7 -0
  71. package/dist/new/versions.js +13 -0
  72. package/dist/pnpm.d.ts +14 -0
  73. package/dist/pnpm.js +37 -0
  74. package/dist/process.d.ts +22 -0
  75. package/dist/process.js +45 -0
  76. package/dist/project.d.ts +22 -0
  77. package/dist/project.js +42 -0
  78. package/dist/root.d.ts +3 -0
  79. package/dist/root.js +24 -0
  80. package/dist/run.d.ts +13 -0
  81. package/dist/run.js +72 -0
  82. package/dist/runtime.d.ts +19 -0
  83. package/dist/runtime.js +1 -0
  84. package/dist/templates.d.ts +26 -0
  85. package/dist/templates.js +46 -0
  86. package/package.json +45 -3
  87. package/templates/app/AGENTS.md.tpl +50 -0
  88. package/templates/app/README.md.tpl +15 -0
  89. package/templates/app/eslint.config.js.tpl +19 -0
  90. package/templates/app/gitignore.tpl +22 -0
  91. package/templates/app/index.html.tpl +12 -0
  92. package/templates/app/mcp.json.tpl +8 -0
  93. package/templates/app/src/App.tsx.tpl +8 -0
  94. package/templates/app/src/i18n.ts.tpl +12 -0
  95. package/templates/app/src/main.tsx.tpl +12 -0
  96. package/templates/app/src/messages/index.ts.tpl +1 -0
  97. package/templates/app/src/providers/app.tsx.tpl +23 -0
  98. package/templates/app/src/providers/repository/index.ts.tpl +5 -0
  99. package/templates/app/src/queries-index.ts.tpl +1 -0
  100. package/templates/app/src/repositories/index.ts.tpl +18 -0
  101. package/templates/app/src/repositories/options.ts.tpl +8 -0
  102. package/templates/app/src/schemas-index.ts.tpl +1 -0
  103. package/templates/app/src/test/render.tsx.tpl +31 -0
  104. package/templates/app/src/test/setup.ts.tpl +4 -0
  105. package/templates/app/typescript.json.tpl +24 -0
  106. package/templates/app/vite.config.ts.tpl +16 -0
  107. package/templates/component/component-test.tsx.tpl +9 -0
  108. package/templates/component/component.tsx.tpl +11 -0
  109. package/templates/domain/queries.ts.tpl +62 -0
  110. package/templates/domain/repository-contract-test.ts.tpl +75 -0
  111. package/templates/domain/repository-contract.ts.tpl +13 -0
  112. package/templates/domain/repository-fixtures.ts.tpl +8 -0
  113. package/templates/domain/repository-index.ts.tpl +12 -0
  114. package/templates/domain/repository-mock.ts.tpl +69 -0
  115. package/templates/domain/schema.ts.tpl +23 -0
  116. package/templates/page/index-domain-test.tsx.tpl +11 -0
  117. package/templates/page/index-test.tsx.tpl +10 -0
  118. package/templates/page/index.tsx.tpl +7 -0
  119. package/templates/page/messages-domain.en.json.tpl +5 -0
  120. package/templates/page/messages-domain.pt-BR.json.tpl +5 -0
  121. package/templates/page/messages.en.json.tpl +3 -0
  122. package/templates/page/messages.pt-BR.json.tpl +3 -0
  123. package/templates/page/model-domain.ts.tpl +17 -0
  124. package/templates/page/model.ts.tpl +8 -0
  125. package/templates/page/view-domain.tsx.tpl +20 -0
  126. package/templates/page/view.tsx.tpl +9 -0
package/README.md CHANGED
@@ -1,3 +1,122 @@
1
- # Temporary Holding Version
1
+ # @matizze/prumo-cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ O comando `prumo`: `new`, `make:page`, `make:domain`, `make:component`, `check` e `doctor`, e a API para rodar os comandos em processo.
4
+
5
+ **Situação:** o Prumo é uma ferramenta sem frontend ([docs/plano.md](../../docs/plano.md)): a CLI cria e confere o projeto, e não traz interface. Os comandos estão prontos. O pacote está pronto para o npm público (sem `private`, com `repository` e `publishConfig` público); o GitHub Packages foi uma etapa provisória. O `prumo new` não cria `.npmrc` (os pacotes `@matizze/prumo-*` vêm do registry padrão), e o `prumo doctor` avisa se o `.npmrc` ainda manda o escopo `@matizze` para o GitHub Packages.
6
+
7
+ ## Comandos
8
+
9
+ | Comando | O que faz |
10
+ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | `prumo new <nome> [--dir <pasta>] [--packages <pasta>] [--no-install] [--dry-run]` | Cria um app mínimo, sem CSS e sem design system, com a estrutura de pastas, os provedores, uma tela inicial, o eslint, o vitest, o `AGENTS.md` e o `.mcp.json`. Veja abaixo. |
12
+ | `prumo make:page <nome> [--domain <domínio>] [--root <pasta>] [--dry-run]` | Gera uma tela (`index`, `model`, `view` e o teste), as mensagens nos idiomas do projeto, o namespace nos índices de mensagens e a rota no `src/App.tsx`. Veja abaixo. |
13
+ | `prumo make:component <nome> (--page <tela> \| --shared) [--root <pasta>] [--dry-run]` | Gera um componente (só HTML) e o teste dele, na pasta da tela ou em `src/components/shared`. Veja abaixo. |
14
+ | `prumo make:domain <nome> [--entity <singular>] [--root <pasta>] [--dry-run]` | Gera um domínio de dados (schema, repositório com mock e contrato, queries com hooks e o teste de contrato) e o registra nos índices e no container. Veja abaixo. |
15
+ | `prumo check [--root <pasta>]` | Analisa o projeto (a análise do [`@matizze/prumo-rules`](../rules/README.md)) e escreve uma linha por violação, com o arquivo e a regra. |
16
+ | `prumo doctor [--root <pasta>]` | Confere o ambiente e o projeto, uma linha por item com ok, aviso ou erro. Não escreve nada e não usa a rede. |
17
+
18
+ `--root` é a pasta do projeto (a que tem o `package.json` e o `src`); o padrão é a pasta atual. Códigos de saída: 0 sem erro, 1 com violação (`check`) ou erro (`doctor`), 2 para uso errado (comando ou opção desconhecidos, pasta que não é um projeto). `prumo --help` e `prumo <comando> --help` mostram a ajuda, em português.
19
+
20
+ ### prumo new
21
+
22
+ `prumo new meu-app` cria `./meu-app` (ou `<dir>/meu-app`, com `--dir`) com o app mínimo do Prumo: Vite, React 19, TypeScript, wouter, TanStack Query, zod e i18next (o que o `@matizze/prumo-core` usa), e **nada de interface** (sem CSS, sem design system, sem Storybook). O app tem:
23
+
24
+ - a estrutura de pastas do plano (`src/pages`, `src/components/shared`, `src/schemas`, `src/repositories`, `src/queries` e `src/messages/{pt-BR,en}`) e os pontos que os geradores pressupõem: `@/` para `src` (tsconfig e vite), `src/i18n.ts`, `src/providers/repository`, `src/repositories/{index,options}.ts` (o container) e `src/test/render.tsx` (o `renderWithProviders`);
25
+ - os provedores (`src/providers/app.tsx`: query, i18n e repositórios) e o `src/main.tsx`;
26
+ - uma tela inicial, `src/pages/home` na rota `/`, gerada pelo mesmo modelo do `make:page` (com o teste e as mensagens nos dois idiomas);
27
+ - o eslint com o plugin do Prumo, o vitest com jsdom, o `AGENTS.md` (as camadas e os comandos, curto) e o `.mcp.json` com o servidor `prumo` (`pnpm exec prumo-mcp`);
28
+ - o `packageManager` no `package.json`, com o pnpm fixado (`pnpm@<versão>`): a versão vem do `npm_config_user_agent` (o pnpm o põe no ambiente em `pnpm dlx`, `pnpm exec` e `pnpm create`) ou, sem ele, de `pnpm --version`; sem nenhuma das duas, o campo fica de fora. Assim o `prumo doctor` do app novo não avisa que falta o `packageManager` (`src/pnpm.ts`);
29
+ - os scripts `dev`, `build`, `typecheck`, `lint`, `check`, `test` e `verify` (typecheck, lint, check e test, sem navegador).
30
+
31
+ As bibliotecas de terceiros têm as versões fixadas nos modelos (`templates/app`), e os cinco pacotes do Prumo entram como `^<versão>` (a versão de cada um está em `src/new/versions.ts`, que o `versions.test.ts` confere contra os `package.json` de `packages/*`: ao subir uma versão, atualize o arquivo). Com `--packages <pasta>` (os tarballs do `pnpm pack:all`), o `package.json` ganha `pnpm.overrides` com `file:` para os tarballs, e o app instala sem registry. Roda `git init` (sem commit) e `pnpm install`, a não ser com `--no-install`; sob o servidor MCP (ou qualquer Runtime sem `inheritStdio`), a saída do `pnpm install` é capturada e volta pelo `runtime.out`/`runtime.err` (`process.ts`), nunca direto no stdout do processo.
32
+
33
+ O app é montado numa pasta de rascunho e só vai ao destino se tudo deu certo. Valida antes de escrever (saída 2): o nome em kebab-case, o destino (não pode existir com conteúdo) e os tarballs (a pasta tem de ter os cinco). `--dry-run` lista os arquivos e não escreve nada.
34
+
35
+ ### prumo make:domain
36
+
37
+ `prumo make:domain clientes` (o nome é o do domínio, no plural e em kebab-case) cria, a partir dos modelos do pacote:
38
+
39
+ | Arquivo | O que tem |
40
+ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41
+ | `src/schemas/entities/cliente.ts` | O schema zod (`id`, `name`, `createdAt`) e o tipo, a entrada de criar e editar (`ClienteInput`) e a consulta da lista (`ClienteListQuery`, com busca, ordem e página) |
42
+ | `src/repositories/clientes/repository.contract.ts` | A interface `IClientesRepository`: `list`, `get`, `create`, `update` e `remove` |
43
+ | `src/repositories/clientes/repository.mock.ts`, `fixtures.ts` | O mock em memória, com a latência simulada e os utilitários de `@matizze/prumo-core/mock`, e os dados de exemplo |
44
+ | `src/repositories/clientes/index.ts` | A fábrica `createClientesRepository`, que o container chama, e os exports do domínio |
45
+ | `src/repositories/clientes/repository.contract.test.ts` | O contrato, com `defineContractSuite` e `runContractSuite` de `@matizze/prumo-testing/contract`, rodado contra o mock |
46
+ | `src/queries/clientes.ts` | As query keys do core, as queries e os hooks `useClientesList`, `useClienteDetail`, `useCreateCliente`, `useUpdateCliente` e `useRemoveCliente` |
47
+
48
+ O domínio é registrado em `src/schemas/index.ts`, em `src/repositories/index.ts` (o import, o `export *` e a entrada no mapa `factories`, que é o container, em ordem alfabética) e em `src/queries/index.ts`. Os três índices podem estar vazios (o de um projeto novo): o primeiro domínio entra sem erro.
49
+
50
+ - **A entidade** é o singular do nome, tirando o `s` final. Onde a regra erra (`categories`, `status`...), o comando recusa e pede `--entity category`.
51
+ - **Os hooks** pegam o repositório de `useRepositories()`, de `@/providers/repository` (o provedor que `createRepositoryContext`, do core, cria), e as mutations invalidam as queries do domínio. O comando avisa se o projeto não tem esse provedor.
52
+ - **Valida antes de escrever** (nome kebab-case e que não é palavra reservada nem nome global, singular suspeito, índice que falta, domínio ou arquivo que já existe): erro de uso sai com 2 e não deixa o projeto pela metade. Nunca sobrescreve.
53
+ - **`--dry-run`** lista o que seria criado e alterado e não escreve nada.
54
+ - **No fim**, roda o `prumo check`: com violação (do projeto, não necessariamente do domínio) sai com 1, já com o domínio gerado. Mostra também o comando dos testes do domínio novo.
55
+
56
+ ### prumo make:page
57
+
58
+ `prumo make:page clientes` (kebab-case) cria, a partir dos modelos, `src/pages/clientes/` com:
59
+
60
+ - `index.tsx`: liga o model à view (`const model = useClientesModel(); return <ClientesView {...model} />`);
61
+ - `model.ts`: o título e os textos, por `useTranslations('clientes')`, sem JSX;
62
+ - `view.tsx`: só elementos HTML semânticos, sem classe e sem componente de design system, e recebe tudo por props;
63
+ - `index.test.tsx`: renderiza com o `renderWithProviders` do projeto (`@/test/render`) e confere o título.
64
+
65
+ Cria `src/messages/<idioma>/clientes.json` em cada idioma do projeto (os `pt` com o texto em português; os outros, em inglês, para a pessoa traduzir), registra o namespace nos índices de mensagens e a rota `/clientes` no `src/App.tsx` (depois da última rota, com o import na ordem dos de `@/pages`; um `<Switch>` sem rota recebe a primeira).
66
+
67
+ Com `--domain clientes`, o model lê a lista do domínio (`useClientesList()`, de `@/queries/clientes`, o que o `make:domain` gera) e devolve `{ title, items, loading, failed }` mais os textos de carregando e de erro, e a view mostra o carregando, o erro e a lista (`<ul>` com `<li key={i.id}>{i.name}</li>`). O comando confere que o domínio existe e tem o hook antes de escrever. Valida o nome, recusa sobrescrever, aceita `--dry-run` e `--root`, roda o `prumo check` no fim (violação sai com 1, já com a tela gerada) e mostra o comando dos testes da tela.
68
+
69
+ ### prumo make:component
70
+
71
+ `prumo make:component resumo --page clientes` gera `src/pages/clientes/components/resumo.tsx` (só HTML, com `ResumoProps`) e `resumo.test.tsx`; `--shared` gera em `src/components/shared/`. É um dos dois: sem nenhum, ou com os dois, o comando recusa (saída 2), e a tela de `--page` precisa existir. O `prumo check` cobra que o que está em `shared` seja usado por duas telas ou mais: um componente `--shared` recém-gerado aparece nessa violação (`shared-usage`), que o comando mostra e explica, e sai com 0. Qualquer outra violação sai com 1.
72
+
73
+ ### prumo doctor
74
+
75
+ - **Node:** erro abaixo do Node 24, o mínimo do Prumo. Aviso se o `.nvmrc` (do projeto ou de uma pasta acima) ou o `engines.node` pedem outra versão.
76
+ - **pnpm:** erro se não existe. Aviso se o `package.json` não tem `packageManager`, se ele não é pnpm, ou se o pnpm instalado é de outra major ou mais antigo.
77
+ - **Pacotes do Prumo:** a versão instalada de cada `@matizze/prumo-*` contra uma faixa compatível (`>=0.1.0 <0.2.0`), não contra a igualdade, porque os pacotes versionam separados. As faixas estão em `src/doctor/ranges.ts`, e o `ranges.test.ts` as compara com o `package.json` de cada pacote do workspace.
78
+ - **`.npmrc`:** só quando ele manda o escopo `@matizze` para o `npm.pkg.github.com`: aviso (nunca falha) de que os pacotes agora estão no npm público e a linha pode sair; sem esse `.npmrc`, nenhuma linha. Nunca lê nem imprime token.
79
+ - **`.mcp.json`:** aviso se não existe, se não é um JSON de objeto ou se não tem o servidor `prumo` (o `prumo-mcp`), com o trecho a acrescentar.
80
+
81
+ ## A API em processo
82
+
83
+ `@matizze/prumo-cli/api` (também exportada na raiz) roda e descreve os comandos sem subprocesso; é o que o servidor [`@matizze/prumo-mcp`](../mcp/README.md) usa. Importar não tem efeito colateral: nada é lido do `process` nem escrito.
84
+
85
+ | Função | O que faz |
86
+ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
87
+ | `runInProcess(argv, { cwd, env? })` | Roda um comando e devolve `{ exitCode, stdout, stderr }`, sem escrever no stdout nem no stderr do processo e sem encerrá-lo. O `argv` é a linha de comando sem o `prumo` (`['check', '--root=app']`). Nada é lido de `process.cwd()` nem de `process.env`, e duas chamadas não compartilham estado. |
88
+ | `describeCommands(root)` | A árvore de comandos como dado, das definições do citty que a ajuda usa: cada comando folha com `name`, `path`, `toolName`, `summary`, `description` e `options`. A raiz é um argumento: `createRoot(runtime)`. |
89
+ | `toolNameOf(nome)` | O nome da ferramenta MCP de um comando: `make:page` vira `make_page`. |
90
+ | `toArgv(command, input)` | Os campos de uma chamada (um por argumento, com o nome da CLI) como linha de comando, sem o nome do comando. Opção de texto vira `--nome=valor`; liga e desliga vira `--nome` (e `--no-nome` se parte ligado); posicional que começa com `-`, campo desconhecido e valor de outro tipo são `UsageError`. |
91
+ | `createRoot(runtime)` e `runCli(...)` | A árvore de comandos e o executor que devolve o código de saída, os mesmos do `bin`. |
92
+
93
+ **O stdout é do protocolo.** No transporte stdio do MCP, uma linha solta no stdout corrompe o JSON-RPC. Por isso os comandos escrevem só pelo `Runtime` (`out`, `err`, `cwd` e `env`), e o `no-leak.test.ts` proíbe `process.stdout`, `process.stderr`, `console.` e `stdio: 'inherit'` em tudo, menos no `bin.ts`.
94
+
95
+ ## Os modelos (`templates/`)
96
+
97
+ Os geradores não copiam tela nem domínio de outro projeto: cada arquivo gerado sai de um modelo em `templates/`, um arquivo `.tpl` com marcadores de nome. O `.tpl` evita que o TypeScript, o ESLint e o Vitest tomem o modelo por código, e o `templates.test.ts` confere que todo arquivo da pasta é usado por um gerador e todo modelo de um gerador existe.
98
+
99
+ - **Marcadores:** `{{plural.kebab}}`, `{{plural.pascal}}`, `{{plural.camel}}` e `{{plural.constant}}` (o mesmo para `singular`, `page`, `domain` e `component`; o `new` usa `{{app.kebab}}` e `{{app.title}}`): para `pedidos-recentes`, `pedidos-recentes`, `PedidosRecentes`, `pedidosRecentes` e `PEDIDOS_RECENTES`. O nome do marcador só tem letras, números e ponto, então um `{{` de JSX não é marcador. Marcador sem valor lança um erro: o gerador não escreve `undefined` no código de ninguém. `src/templates.ts` troca os marcadores (`renderTemplate`) e monta os valores de um nome (`nameVars`).
100
+ - **Caminhos:** cada gerador (`src/generate/<nome>.ts`) lista os pares modelo e destino, o destino também com marcadores (`src/repositories/{{plural.kebab}}/index.ts`), e monta tudo num `ChangePlan` em memória, junto com as costuras.
101
+ - **No tarball:** `templates/` está no `files` do `package.json`, e o caminho (`templates/`, um nível acima de `src/` e de `dist/`) vale no workspace e no pacote instalado. O `packaging.test.ts` confere que o tarball leva os mesmos arquivos e gera um domínio com o `prumo` empacotado.
102
+ - **O código gerado compila e roda:** o `generate/page.compile.test.ts` monta um projeto como o do `prumo new` (App sem rota, índices vazios, i18n, provedores e `renderWithProviders`), gera um domínio, três telas (uma com `--domain`) e dois componentes, e roda nele o `tsc` (estrito), o Vitest e o `prumo check`. O `generate/domain.compile.test.ts` cria um projeto mínimo, gera três domínios (um com nome composto e entidade explícita), e roda nele o `tsc` (estrito) e o Vitest, com o contrato de cada mock e os hooks de verdade.
103
+
104
+ ## O codemod (interno)
105
+
106
+ `src/codemod/` guarda as costuras dos geradores: o `make:domain` usa as dos índices do domínio, e o `make:page` as das mensagens e da rota.
107
+
108
+ - **`ChangePlan`** (`plan.ts`): o plano de mudanças em memória, sobre um `Project` do ts-morph sem tsconfig e sem checagem de tipos. Recebe arquivos novos e costuras, lista o que seria criado e alterado (`summary()`, o `--dry-run`) e só grava no `commit()`: um erro no meio do caminho não deixa o projeto pela metade.
109
+ - **Nomes** (`names.ts`): valida o nome (kebab-case) e deriva Pascal, camel e, para domínios, singular e plural.
110
+ - **Rota** (`add-route.ts`): registra a rota de uma tela no `src/App.tsx`, com o import na ordem dos de `@/pages`. `addRouteSnippet` recebe o `<Route>` pronto em JSX (o que o `make:page` usa, sem `App.tsx` de origem); `addRoute` copia o de um `App.tsx` de origem.
111
+ - **Mensagens** (`register-messages.ts`, `messages.ts`): registra um namespace nos `index.ts` de cada idioma, em ordem alfabética, também num índice sem nenhum import (só o `export default {}`).
112
+ - **Domínio** (`register-domain.ts`, `merge-barrel.ts`): os exports de `src/schemas/index.ts` e de `src/queries/index.ts` e o import, o `export *` e o mapa `factories` de `src/repositories/index.ts`, também num índice sem nenhum domínio; o `mergeBarrel` acrescenta ao barrel os exports de outro barrel que faltam.
113
+
114
+ Os testes montam um projeto pequeno numa pasta temporária (`src/codemod/test-support.ts`) e não leem nada fora do pacote.
115
+
116
+ ## Build e empacotamento
117
+
118
+ No workspace, o `exports` do pacote aponta para o código-fonte (`src/*.ts`), e o bin roda com um Node que executa `.ts` (Node 24 ou mais novo). Fora do monorepo o Node não faz type stripping dentro de `node_modules`, então o pacote tem `tsconfig.build.json` e o script `build` (`pnpm --filter @matizze/prumo-cli run build`), que emite o `dist/` com `.js` e `.d.ts`, sem os testes e os arquivos de apoio. O `publishConfig` troca `exports`, `types` e `bin` para o `dist/`, e o tarball leva só o `dist/`, os `templates/`, o `package.json` e o README. `pnpm pack:all`, na raiz, empacota os cinco pacotes, e o `packaging.test.ts` confere os tarballs e roda o `prumo` empacotado fora do monorepo.
119
+
120
+ ## Dependências
121
+
122
+ `@matizze/prumo-rules` (`workspace:*`, a análise do `check`), `citty` (a árvore de comandos) e `ts-morph` (o codemod).
package/dist/api.d.ts ADDED
@@ -0,0 +1,10 @@
1
+ /**
2
+ * A API em processo do `@matizze/prumo-cli`, para o servidor MCP: rodar um comando
3
+ * sem subprocesso e descrever a árvore de comandos como dado. Importar este módulo não tem efeito
4
+ * colateral (não lê o `process` nem escreve nada); o `bin.ts` é quem roda a CLI.
5
+ */
6
+ export { describeCommands, toArgv, toolNameOf, type CommandInfo, type OptionInfo, type OptionKind, } from './describe.js';
7
+ export { runInProcess, type InProcessOptions, type InProcessResult } from './in-process.js';
8
+ export { createRoot } from './root.js';
9
+ export { runCli } from './run.js';
10
+ export type { Runtime } from './runtime.js';
package/dist/api.js ADDED
@@ -0,0 +1,9 @@
1
+ /**
2
+ * A API em processo do `@matizze/prumo-cli`, para o servidor MCP: rodar um comando
3
+ * sem subprocesso e descrever a árvore de comandos como dado. Importar este módulo não tem efeito
4
+ * colateral (não lê o `process` nem escreve nada); o `bin.ts` é quem roda a CLI.
5
+ */
6
+ export { describeCommands, toArgv, toolNameOf, } from "./describe.js";
7
+ export { runInProcess } from "./in-process.js";
8
+ export { createRoot } from "./root.js";
9
+ export { runCli } from "./run.js";
package/dist/args.d.ts ADDED
@@ -0,0 +1,11 @@
1
+ import { type ArgsDef } from 'citty';
2
+ /**
3
+ * Confere os argumentos de um comando antes de rodá-lo e lança um `UsageError` (saída 2) em
4
+ * português quando algo está errado: opção que o comando não tem, opção sem valor, valor fora da
5
+ * lista, argumento ou opção obrigatória que falta, argumento a mais.
6
+ *
7
+ * O citty não faz isso sozinho: o parser dele aceita qualquer opção (uma opção com erro de
8
+ * digitação passaria calada) e as mensagens dele são em inglês. Então ele só separa os argumentos,
9
+ * com as obrigações desligadas, e as conferências são daqui.
10
+ */
11
+ export declare function validateArgs(argsDef: ArgsDef, rawArgs: string[]): void;
package/dist/args.js ADDED
@@ -0,0 +1,61 @@
1
+ import { parseArgs } from 'citty';
2
+ import { UsageError } from "./errors.js";
3
+ import { aliasesOf, isRequired, isVariadic } from "./help.js";
4
+ const toKebab = (text) => text.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
5
+ const toCamel = (text) => text.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase());
6
+ /**
7
+ * Confere os argumentos de um comando antes de rodá-lo e lança um `UsageError` (saída 2) em
8
+ * português quando algo está errado: opção que o comando não tem, opção sem valor, valor fora da
9
+ * lista, argumento ou opção obrigatória que falta, argumento a mais.
10
+ *
11
+ * O citty não faz isso sozinho: o parser dele aceita qualquer opção (uma opção com erro de
12
+ * digitação passaria calada) e as mensagens dele são em inglês. Então ele só separa os argumentos,
13
+ * com as obrigações desligadas, e as conferências são daqui.
14
+ */
15
+ export function validateArgs(argsDef, rawArgs) {
16
+ const entries = Object.entries(argsDef);
17
+ const loose = Object.fromEntries(entries.map(([name, def]) => [name, loosen(def)]));
18
+ const parsed = parseArgs(rawArgs, loose);
19
+ const known = new Set(['_']);
20
+ for (const [name, def] of entries) {
21
+ for (const key of [name, toCamel(name), toKebab(name), ...aliasesOf(def)])
22
+ known.add(key);
23
+ }
24
+ for (const key of Object.keys(parsed)) {
25
+ if (!known.has(key))
26
+ throw new UsageError(`opção desconhecida: '${flagOf(key)}'.`);
27
+ }
28
+ for (const [name, def] of entries) {
29
+ const value = parsed[name];
30
+ if (def.type === 'positional') {
31
+ if (value === undefined && isRequired(def))
32
+ throw new UsageError(`falta o argumento <${isVariadic(name) ? name.slice(0, -3) : name}>.`);
33
+ continue;
34
+ }
35
+ if (value === undefined) {
36
+ if (isRequired(def))
37
+ throw new UsageError(`a opção --${name} é obrigatória.`);
38
+ continue;
39
+ }
40
+ if (def.type === 'boolean')
41
+ continue;
42
+ if (value === '')
43
+ throw new UsageError(`a opção --${name} precisa de um valor.`);
44
+ if (def.type === 'enum' && def.options?.length && !def.options.includes(String(value))) {
45
+ throw new UsageError(`valor inválido para --${name}: '${String(value)}'. Valores aceitos: ${def.options.join(', ')}.`);
46
+ }
47
+ }
48
+ const positionals = entries.filter(([, def]) => def.type === 'positional');
49
+ // O último argumento posicional pode aceitar vários valores (`item...`): o que sobra é dele
50
+ const variadic = isVariadic(positionals.at(-1)?.[0]);
51
+ const extra = parsed._[positionals.length];
52
+ if (extra !== undefined && !variadic)
53
+ throw new UsageError(`argumento inesperado: '${extra}'.`);
54
+ }
55
+ /** A mesma definição sem obrigação e sem lista de valores, para o citty só separar os argumentos. */
56
+ function loosen(def) {
57
+ return (def.type === 'enum' ? { ...def, type: 'string', required: false } : { ...def, required: false });
58
+ }
59
+ function flagOf(key) {
60
+ return key.length === 1 ? `-${key}` : `--${key}`;
61
+ }
package/dist/bin.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/bin.js ADDED
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+ import { createRoot } from "./root.js";
3
+ import { runCli } from "./run.js";
4
+ const runtime = {
5
+ out: (text) => process.stdout.write(text),
6
+ err: (text) => process.stderr.write(text),
7
+ cwd: process.cwd(),
8
+ env: process.env,
9
+ inheritStdio: true,
10
+ };
11
+ process.exitCode = await runCli(createRoot(runtime), process.argv.slice(2), runtime);
@@ -0,0 +1,66 @@
1
+ import { type SourceFile } from 'ts-morph';
2
+ import type { ChangePlan } from './plan.js';
3
+ /** A rota de uma tela, como a costura a recebe: o componente, de onde importá-lo e o `path`. */
4
+ export interface RouteSpec {
5
+ /** O componente padrão da tela: `ProductsListPage`. */
6
+ component: string;
7
+ /** De onde o `App.tsx` o importa: `@/pages/products-list`. */
8
+ importPath: string;
9
+ /** O `path` do `<Route>` como está no `App.tsx` da origem: `/invoices/:id`, ou `/general` num `nest`. */
10
+ path: string;
11
+ /** O `path` do `<Route nest>` que envolve a rota, se houver: `/ai-settings`. */
12
+ prefix?: string;
13
+ /** O layout entre o `nest` e a rota: `AiSettingsLayout`. */
14
+ layout?: string;
15
+ }
16
+ /** O texto e o `package.json` de uma origem, que `addRoute` consulta. */
17
+ interface Origin {
18
+ /** O `src/App.tsx` da origem, já aberto no plano (só leitura). */
19
+ app: SourceFile;
20
+ }
21
+ /** Abre o `App.tsx` da origem no ts-morph do plano, sem torná-lo parte do plano (não é gravado). */
22
+ export declare function openOriginApp(plan: ChangePlan, file: string): Origin;
23
+ /**
24
+ * Faz no `src/App.tsx` do projeto a costura da rota de uma tela, clonando o `<Route>`
25
+ * do `src/App.tsx` da origem:
26
+ *
27
+ * - tela de primeiro nível: o `<Route>` da origem (com a casca e o layout dele) entra depois da
28
+ * última rota com `path` do `<Switch>` mais externo;
29
+ * - tela de um `<Route nest>` (`prefix`): se o projeto já tem o `nest`, a rota da tela entra no
30
+ * `<Switch>` dele; se não tem, entra o `<Route>` de primeiro nível da origem, só com ela.
31
+ *
32
+ * O import do componente entra na posição alfabética dos de `@/pages`, e os nomes que o clone usa
33
+ * (layouts, `Redirect`) ganham import se o projeto tem o módulo. Tela que o `App.tsx` já usa fica
34
+ * como está (devolve `false`). Rota repetida ou conflitante, `App.tsx` ou `<Switch>` que falta,
35
+ * nome que o `App.tsx` não tem e não dá para importar: `UsageError`, sem escrever nada.
36
+ */
37
+ export declare function addRoute(plan: ChangePlan, origin: Origin, spec: RouteSpec): boolean;
38
+ /** A rota de uma tela como um trecho de JSX pronto, para a costura que não tem um `App.tsx` de origem. */
39
+ export interface RouteSnippet {
40
+ /** O componente padrão da tela: `ClientesPage`. */
41
+ component: string;
42
+ /** De onde o `App.tsx` o importa: `@/pages/clientes`. */
43
+ importPath: string;
44
+ /** O `path` do `<Route>` do trecho: `/clientes`. */
45
+ path: string;
46
+ /**
47
+ * O `<Route>` como entra no `App.tsx`, em JSX: `<Route path="/clientes">...</Route>`. As linhas
48
+ * depois da primeira são recuadas em relação à primeira, e a costura soma o recuo do destino.
49
+ */
50
+ element: string;
51
+ }
52
+ /**
53
+ * Faz no `src/App.tsx` do projeto a costura da rota de uma tela a partir de um trecho de JSX
54
+ * pronto (o `<Route>` que o gerador montou), sem um `App.tsx` de origem para clonar:
55
+ *
56
+ * - o trecho entra no `<Switch>` mais externo, depois da última rota com `path` (ou antes da rota
57
+ * curinga, ou sozinho num `<Switch>` vazio), com o recuo do destino;
58
+ * - o import do componente entra na posição alfabética dos de `@/pages`.
59
+ *
60
+ * Tela que o `App.tsx` já usa fica como está (devolve `false`). Rota repetida ou conflitante,
61
+ * `App.tsx` ou `<Switch>` que falta, componente já declarado sem rota e nome do trecho (um layout,
62
+ * um guarda) que o `App.tsx` não declara nem importa: `UsageError`, sem escrever nada. Trecho que
63
+ * não é um `<Route>` com o `path` e o componente da costura é erro de quem chama (`Error`).
64
+ */
65
+ export declare function addRouteSnippet(plan: ChangePlan, spec: RouteSnippet): boolean;
66
+ export {};