cli.pt-BR.md

CLI do Repo2C4

Os comandos offline inspect, generate e validate não chamam IA, abrem pull request, avaliam MSBuild nem transformam candidatos em arquitetura runtime confirmada. O comando opcional infer usa o Ollama local ou, com autorização explícita, o provedor cloud OpenAI para propor um modelo sujeito a revisão humana.

Comandos

Inspect

repo2c4 inspect --repository PATH --output snapshot.json

Para anexar um InspectionReport schema 1.6+ previamente gerado pelo DotNetRepoInspector, informe um arquivo dentro do repositório. O Repo2C4 lê somente o boundary JSON público; ele não executa o DotNetRepoInspector:

repo2c4 inspect --repository PATH --integration-report PATH/artifacts/inspection.json --output snapshot.json

O caminho pode ser absoluto ou relativo ao repositório, mas deve resolver para um arquivo regular, sem links, dentro da raiz selecionada. O stdout continua contendo somente o caminho do snapshot; a contagem de evidências external.* importadas vai para stderr. Reports incompatíveis ou inseguros falham sem produzir snapshot.

inspect inventaria um repositório local explicitamente selecionado e extrai apenas as evidências limitadas suportadas pelo Core. A saída é JSON v1 canônico.

O identificador do repositório é derivado de forma determinística do nome do diretório raiz selecionado. Ele é um rótulo local estável, não uma identidade globalmente única.

O arquivo de snapshot não pode existir previamente. Use outro caminho caso exista.

Infer (IA local ou cloud autorizada)

repo2c4 infer --snapshot snapshot.json --provider ollama --model-id IDENTIFICADOR --output candidate.json

Para usar a OpenAI na nuvem, informe --provider openai --allow-external-ai e disponibilize OPENAI_API_KEY no ambiente do host. A CLI apresenta a quantidade de arquivos anonimizados e evidências sanitizadas antes do envio ao endpoint HTTPS fixo; sem consentimento ou chave nenhuma requisição externa é realizada. O uso pode gerar custo conforme modelo/tokens e os metadados transmitidos deixam a máquina. Consulte consentimento, custo e confidencialidade.

As opções --endpoint http://127.0.0.1:11434/ e --timeout-seconds 90 configuram porta local e timeout. São aceitos somente endpoints HTTP loopback. O adaptador envia apenas uma projeção sanitizada e limitada das evidências, nunca arquivos brutos, segredos, caminhos originais ou descrições livres. A CLI valida o contrato v1, anexa localmente o snapshot original e obriga revisão humana de todas as afirmações propostas pela IA. Ela recusa respostas inválidas, modelo indisponível, timeout e sobrescrita do arquivo de saída. Veja o tutorial de inferência local e revisão.

Generate

repo2c4 generate --model architecture.json --output DIR

A entrada deve ser um ArchitectureModel v1 válido, proposto ou revisado por uma pessoa. O comando não infere um modelo C4 a partir do snapshot.

A geração base C1/C2 produz:

• specification.c4
• model.c4
• views.c4
• evidence-report.md

Quando C3 é selecionado, c3.views.c4 é adicionado. Quando o snapshot do modelo contém fatos Semantic C3 persistidos, a geração também adiciona semantic-c3-evidence-report.md.

A geração é somente preview por padrão. O Repo2C4 informa added, modified, unchanged ou conflict para cada saída gerenciada e não altera o filesystem.

Para aplicar um preview já revisado:

repo2c4 generate --model architecture.json --output DIR --apply

A primeira aplicação bem-sucedida cria .repo2c4-manifest.json, contendo a versão de schema do modelo e o SHA-256 de cada saída gerenciada. Aplicações posteriores só são permitidas quando o arquivo atual ainda corresponde ao hash do manifesto. Arquivos editados manualmente, ausentes apesar de previamente gerenciados, linkados ou arquivos não gerenciados que colidem com uma saída são conflitos e permanecem intocados.

evidence-report.md relaciona as afirmações do modelo aos IDs de evidência e às localizações relativas do repositório, separa hipóteses pendentes, avisos de varredura e itens sem suporte, sem copiar corpos de código nem valores sensíveis. Consulte relatório de evidências e revisão arquitetural.

Para solicitar C3 de um ou mais containers C2 revisados, repita --c3-container ID:

repo2c4 generate \
  --model architecture.c2.json \
  --output DIR \
  --c3-container el_web \
  --c3-container el_worker

Quando o snapshot inspecionado contém semanticC3Facts, os containers selecionados usam os classificadores Semantic C3 em vez do agrupamento genérico legado. Nome de classe sozinho não é promovido: candidatos HTTP/application/worker/mensageria/persistence/integração exigem proveniência estrutural. Snapshots antigos sem fatos semânticos mantêm o fallback C3 genérico. Veja Semantic C3.

Uma única ocorrência de --c3-container permanece compatível com o comportamento anterior. Com múltiplas seleções, o Repo2C4 constrói um único workspace canônico sobre o mesmo modelo/snapshot C2, aninha cada conjunto de componentes no seu container em um único model.c4 e grava um único c3.views.c4 com uma view C3 determinística por container selecionado. A ordem dos argumentos não altera a saída e IDs repetidos são deduplicados.

Sem essa opção nenhum arquivo C3 é gerado. IDs desconhecidos, actors/software systems usados como seleção C3 e C3 solicitado sobre um modelo C1 falham como dados inválidos antes do preview ou da escrita gerenciada. Um container selecionado sem evidência C3 suficiente também falha em vez de fabricar componentes.

Alterar o conjunto de containers selecionados é tratado como uma modificação normal das saídas gerenciadas quando os arquivos atuais ainda correspondem ao manifesto. Edições manuais existentes continuam protegidas como conflito e nunca são sobrescritas automaticamente.

O diretório de saída e os arquivos gerenciados precisam permanecer dentro da raiz escolhida e não podem ser symlink, junction ou reparse point. Os nomes gerados são fixos pelo Repo2C4 e não podem ser definidos pelo conteúdo do modelo. As escritas são preparadas em um diretório transacional; o manifesto só é substituído após a preparação das saídas. Em caso de falha, arquivos previamente gerenciados são restaurados em best effort e arquivos desconhecidos nunca são excluídos.

Validate

repo2c4 validate --output DIR

validate chama a CLI oficial do LikeC4 instalada no ambiente usando apenas o comando controlado likec4 validate. O Repo2C4 não instala Node.js nem LikeC4 em runtime. A baseline do CI usa LikeC4 1.59.4; consulte validação pela CLI do LikeC4.

Códigos de saída

Código	Significado
0	Comando concluído com sucesso.
2	Comando ou argumentos incorretos.
3	Snapshot/modelo v1 inválido.
4	Validação LikeC4 falhou ou a CLI configurada não conseguiu validar.
5	Operação local de arquivo/caminho falhou ou a política de overwrite bloqueou a operação.
6	Provedor de inferência indisponível, requisição recusada ou tempo limite excedido.

O código original do LikeC4 aparece apenas como contexto diagnóstico e é mapeado para o código 4 do Repo2C4.

Limite de inferência

O fluxo suportado é deliberadamente separado:

repositório local
    -> inspect
    -> snapshot de evidências
    -> proposta/revisão humana
    -> ArchitectureModel
    -> generate
    -> arquivos LikeC4
    -> validate

O Repo2C4 não converte automaticamente todo projeto .NET em container C4. Referências de build e candidatos de pacote/runtime permanecem evidências ou hipóteses até serem explicitamente revisados no modelo.

Exemplo reproduzível

Consulte o exemplo end-to-end versionado. Ele usa a fixture apenas-biblioteca para demonstrar que a ausência de executável é preservada: o modelo C2 revisado não fabrica um container.