theforge-cli 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,230 @@
+# Changelog
+
+Todas as mudanças notáveis deste projeto são documentadas aqui, no
+formato [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/).
+
+## [Não lançado]
+
+### Programa ecosystem-2026 (cyc8-05)
+
+#### Added
+
+- **Compatibilidade com o manifesto do ecossistema**: `src/compat.ts`
+  consome `forge/EcosystemCompatibility/v1` (the-forge
+  `ecosystem-compatibility.json`) — `update --check` reporta
+  `installed_compat: certified|incompatible|unknown` por repositório e o
+  banner do manifesto (release + sha256) na saída texto.
+- **Validação estrita do manifesto**: `manifestProblems()` espelha
+  `load_manifest(strict=True)` do Python — release `YYYY.MM`, `created_at`
+  ISO, ids de componente/família/contrato, versão pinada (rejeita
+  `latest`/`""`) no scheme declarado, `source` obrigatório, janelas
+  `min_major`/`max_major`, famílias únicas. Manifesto inválido → `null`
+  (nunca certifica silenciosamente).
+
+#### Changed
+
+- **`update --check --json`**: o payload passa de array puro de
+  repositórios para envelope `{manifest: {release, sha256, path} | null,
+repos: [...]}` — a identidade do manifesto avaliado agora é evidência no
+  JSON. Consumidores do array anterior devem ler `payload.repos`.
+- **`compat:` → `installed_compat:`** no texto e no JSON: o veredito se
+  refere à versão **instalada**, não ao update pendente (repos `behind`
+  não sugerem mais que a atualização é certificada).
+
+### Programa evo-cli-portal (F0→C6, ciclos `audit/f0-baseline`→`cycle/c6-intelligence`)
+
+#### Added
+
+- **Contratos canônicos (C1)**: família `forge/<Name>/v1` como JSON Schemas
+  em `contracts/schemas/` (Descriptor, Capability, EnvironmentSchema,
+  HostDescriptor, InstallContract, OperationPlan, OperationReceipt,
+  HealthReport), validator Python vendorizável (`contracts/forge_contracts.py`,
+  stdlib-only), política de descoberta com os sete estados
+  (`declared/detected/configured/integrated/validated/degraded/unknown`) e
+  precedência explícita (`src/discovery/negotiate.ts`).
+- **Descoberta e recomendação (C2)**: `forge-cli discover` (walk bounded por
+  budget, sinais de stack, probes de host, `truncated` honesto) e
+  `forge-cli recommend` (recomendações explicáveis com confidence).
+- **Wizard de instalação (C2)**: fluxo interativo de 7 passos + planner que
+  emite `forge/ForgeOperationPlan/v1` com hash sha256 canônico verificável.
+- **Env Intelligence (C2)**: `forge-cli env inspect|plan|init|validate|
+migrate|doctor` — valores nunca exibidos, migração com rollback.
+- **Host Intelligence (C2/C4)**: adapters por host (`forge-cli hosts
+list|plan|register|validate|rollback`) — detecção ≠ validação
+  (`verified|absent|unknown`), comando copiável em vez de escrita opaca.
+- **Ciclo de vida (C2)**: `lock`, `profile`, `recover`, análise de
+  breaking-changes, estado persistido.
+- **Doctor 2.0 + self-healing (C5)**: `forge-cli doctor` cobre 5 domínios
+  (`forge/DoctorReport/v1`, health score gated — `HEALTH_MODEL.md`);
+  `forge-cli heal` com classificação `SAFE_AUTOMATIC`/`REVIEW_REQUIRED`/
+  `MANUAL_ONLY`/`UNSUPPORTED`, fluxo de reparo em 8 passos, receipts
+  imutáveis (`forge/RepairReceipt/v1`) com correlation IDs.
+- **Observabilidade e versões (C5)**: métricas locais, `versions`,
+  overhead medido (PERFORMANCE_BASELINE.md).
+- **Forge Intelligence Engine (C6)**: `forge-cli ask <domínio>`
+  (discovery/recommendation/repair — respostas com evidência, confidence,
+  ordenação estável), `forge-cli predict` (compatibilidade preditiva com
+  evidência/versão/certainty — silêncio honesto sem evidência),
+  `forge-cli context` (`forge/ForgeContext/v1`, 8 KiB bounded).
+- **Modo IA opcional (C6)**: `forge-cli ai <task>` — opt-in, BYOK via
+  bridge configurável (`ai.command`), sanitize tripla de segredos,
+  propostas schema-validadas (`forge/AiProposal/v1`) com refs
+  re-validados e rechecagem determinística; **zero execução** de conteúdo
+  do modelo; fallback tipado para determinístico (`AI_MODE_POLICY.md`).
+- **Portabilidade (C6)**: `forge-cli bundle export|import|verify`
+  (`forge-cli/Bundle/v1`) — profile, env lock + check, pins, manifesto de
+  integridade sha256 (`forge/IntegrityManifest/v1`); valores de segredo
+  excluídos por default (`env-values.json` só com whitelist explícita e
+  recusa fail-closed de chaves secretas); `planReinstall` gera plano
+  verificável (`PORTABILITY.md`).
+- **Aprendizado local (C6)**: `forge-cli learning status|enable|disable|
+report` — opt-in, `.forge-cli/learning.json` bounded a 1000
+  observações, redacted, FIFO, nunca altera política (`LEARNING_EVAL.md`).
+
+#### Changed
+
+- `forge.json` passa a ser validado contra `ForgeDescriptor/v1` quando o
+  campo `schema` é declarado — fail-closed, aditivo.
+- Ordenações em intel/predict usam comparação por code-unit (estável,
+  independente de locale).
+- `bundle export` aceita chaves não-secretas posicionais para inclusão
+  explícita de valores.
+
+#### Fixed
+
+- `doctor`/`env`/`hosts`/`discover`/`recommend`/`context`/`predict`
+  respeitam `--json` sem banner (via `JSON_QUERY_COMMANDS`).
+- `bundle export` captura `SecretKeysRefusedError` e exibe recusa clara.
+- Heal: `REVIEW_REQUIRED` nunca é aplicado por `--yes` — aguarda revisão
+  por chave (Gate C5).
+
+#### Security
+
+- Logs, receipts e erros mascaram segredos (`redactSecrets`); contexto de
+  IA usa denylist de chave + redact + detecção de valor-secret-shaped
+  (`sk-live-`, `ghp_`, JWT, `AKIA`, `xox*`).
+- `assertNoSecrets` devolve paths ofensores ordenados; cache de IA bounded
+  (32 entradas, TTL, anti clock-skew, chave sha256 de JSON canônico).
+- Bridge de IA tem boundary injetável único, timeout, cap de contexto e
+  nenhum payload de comando na saída do modelo.
+- `npm ci` auditado, zero vulnerabilidades; runtime deps congeladas.
+
+#### Compatibility
+
+- Sem novas dependências de runtime desde F0; Node >= 20, npm >= 10.
+- Contratos são aditivos: `forge/PortalApi/1` intocado; Forjas
+  consumidoras não requerem mudança.
+- `--offline` usa apenas clones locais; clone ausente → recusa explícita
+  (sem tentativa de rede).
+
+#### Migration
+
+- Nenhuma migração obrigatória. `forge.json` legado continua válido
+  (campos desconhecidos ignorados); `env migrate` oferece plano+rollback.
+
+#### Known limitations
+
+- Preview de plano exibe `git pull` mesmo com `--offline` (cosmético —
+  execução honra a flag; P3).
+- Sem lock cross-process entre dois CLIs no mesmo target (P2).
+- Manifests de Forja (`forge/SpecialistAgenticManifest/v1`) ainda não
+  emitidos pelos repos consumidores — engine reporta silêncio correto.
+- Defect pré-existente em `forge-doctor-api`
+  (`test_malformed_stdio_input_resilient`) descoberto na homologação —
+  escopo do especialista, P2.
+
+### Adicionado
+
+- Licença MIT (`LICENSE`, campo `license`), alinhada às demais Forjas.
+- `forge-doctor-api`: `update`/`uninstall` nativos e `--host`/`--gateway-profile`
+  confirmados em `scripts/forge_install.py`.
+- Testes de TUI com teclas reais simuladas (menu e seleção com busca) e fluxo
+  do menu testável sem TTY (`applyMenu`).
+
+### Corrigido
+
+- Ajuda da seleção de Forjas dizia "espaço marca"; a tecla correta é Tab.
+- Instaladores nativos (itens 6/7/9/10): `forge-doctor-api` via
+  `scripts/forge_install.py` (Python resolvido em runtime), `--host` e
+  `--gateway-profile` repassados onde a Forja suporta, `--native` em
+  `update` e `uninstall`, e `forge.json` opcional (campos validados)
+  para derivar a verificação de Forjas sem `verify` no catálogo.
+- `--json` em `status`, `list`, `versions`, `components`, `update --check`
+  e `doctor`: só JSON no stdout, sem banner.
+- TUI: seleção de Forjas com busca (digite para filtrar) e dica de fase/versão
+  por Forja; `--verbose` para saída completa dos comandos; logs com
+  timestamp. Código de saída 1 quando alguma Forja falha.
+
+### Corrigido
+
+- O log da execução (`.forge-cli/logs`) agora mascara segredos e URLs com
+  credenciais; antes só relatórios e mensagens de erro eram mascarados.
+- Aprovação e estados (pós-roadmap): resumo de execução (origem, revisão,
+  confiança, comandos exatos) antes da confirmação, aprovação por
+  repositório customizado, e fases persistidas (`cloned`, `prepared`,
+  `installed`, `validated`, `partial`, `failed`, `drifted`) no `status`.
+- `help`, `components [forjas]` (flags do instalador nativo por Forja),
+  `doctor <forja>` e `--offline` (usa só clones existentes; nunca clona
+  nem faz pull/fetch).
+- Adaptadores leves (Cycle 0/6): `--profile`, `--scope` e `--components`
+  acionam o instalador nativo da Forja (`<cli> install ...`) depois do
+  bootstrap, somente para Forjas que o documentam; sempre `--dry-run`
+  salvo `--yes`. Matriz de capacidades real em `docs/capabilities.md`.
+- Portabilidade/distribuição (Cycle 8/9): `self update` respeitando o
+  método de instalação (npm global automático com `--yes`; shim e
+  código-fonte mostram o passo manual), CI em Linux/Windows/macOS e
+  testes dos cenários de independência A–F.
+- TUI (Cycle 2): menu principal ao rodar `forge-cli` em terminal
+  interativo (instalar, atualizar, reinstalar, reparar, versões, estado,
+  desinstalar, diagnosticar, sair). Sem TTY ou com comando/flags de
+  seleção, o comportamento anterior é mantido. `uninstall` pede
+  confirmação interativa quando não há `--yes`.
+- Ciclo de vida (Cycle 4/5/7): `pin`/`unpin` (install/update respeitam a
+  fixação), `rollback` (só o checkout Git, ao HEAD anterior registrado),
+  `reinstall` (mantém a revisão atual; `--clean` remove e reclona com
+  backup) e `uninstall <forjas>` (plano por padrão, exige `--yes`; recusa
+  tree suja, remote diferente, symlink e diretórios sem .git; faz backup
+  de `.env`/configs em `.forge-cli/backups`).
+- Versões e revisões (Cycle 3/5): `update [forjas]` (sem nomes: todas as
+  clonadas), `update --check` (só fetch, sem alterar), `versions`,
+  `--ref <sha|tag>` e `--version <tag>` (checkout destacado; recusa
+  working tree modificada; exige uma única Forja).
+- Subcomandos (Cycle 3): `install [forjas]`, `clone <forjas>` (sem
+  scripts), `status [forjas]`, `self install|uninstall`. **Mudança:**
+  `forge-cli install` sem nomes agora abre o fluxo interativo; o
+  registro no PATH é `forge-cli self install`.
+- Sync Git (Cycle 1): detecta remote divergente do catálogo e classifica
+  falhas de pull (divergente/rede/autenticação). Scripts não rodam após
+  falha de sync sem `--run-after-sync-failure`; repositórios de
+  `forge-cli.repos.json` só executam scripts com `--trust-custom`.
+- Segurança (Cycle 1): validação de nomes/URLs de repositórios (bloqueia
+  path traversal, `--opção`, `ext::`, `file://` e credenciais embutidas),
+  recusa de destino symlink/junction, `git clone --`, redação de
+  segredos em logs/relatórios/erros e escrita atômica de estado.
+- Provisionamento de `.env` por repositório antes do script de
+  instalação: copia `.env.example`, cria modelo comentado ou preserva
+  `.env` existente (lf-0002).
+- Verificação de ambiente (preflight): `git`, Node.js >= 20 e
+  `powershell.exe` no Windows, com saída `exit 1` antes dos prompts.
+- UI/UX: banner animado, tema de cores centralizado, ícones emoji,
+  spinners com cronômetro, tempo por repositório e relatório final
+  enriquecido.
+
+### Alterado
+
+- Refatoração interna: `index.ts` reduzido a orquestrador; novos
+  módulos `prompts`, `runner`, `report`, `env`, `preflight` e
+  `ui/{theme,strings}` (lf-0002).
+
+## [0.1.0] - 2026-10-11
+
+### Adicionado
+
+- CLI interativa que clona/atualiza os 8 repositórios do ecossistema
+  Forge e executa `install.ps1` (Windows) ou `install.sh`
+  (Linux/macOS) (lf-0001).
+- Fluxo `@clack/prompts`: diretório de destino (padrão
+  `./forge-workspace`), multiseleção, confirmação, spinners e
+  relatório `[OK]`/`[AVISO]`/`[ERRO]`.
+- Cancelamento limpo via `isCancel()` e `SIGINT`.
+- Testes `vitest` para o catálogo e utilitários de sistema.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edgar Sócrates Caria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,246 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="docs/assets/logo.png" alt="Forge Cli" width="440">
+</p>
 
-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.
+# Forge-CLI
+
+CLI interativa para clonar e configurar o ecossistema **Forge**: oito
+repositórios, um comando. O forge-cli resolve o diretório de destino,
+sincroniza cada repositório (clone ou pull), provisiona o arquivo `.env`
+e executa o script de instalação do sistema operacional — tudo com
+feedback visual em tempo real.
+
+## Funcionalidades
+
+- **Fluxo 100% interativo** com `@clack/prompts`: banner animado,
+  prompts, spinners com cronômetro e relatório final consolidado.
+- **Sincronização inteligente**: faz `git clone` quando o repositório
+  não existe e `git pull` quando a pasta já contém `.git`.
+- **Provisionamento de `.env`**: antes de qualquer script de
+  instalação, copia `.env.example` para `.env` ou cria um modelo com
+  comentários. Um `.env` existente nunca é sobrescrito.
+- **Scripts por sistema operacional**: `install.ps1` no Windows e
+  `install.sh` no Linux/macOS, detectados automaticamente.
+- **Verificação de ambiente (preflight)**: confirma `git`, Node.js
+  > = 20 e `powershell.exe` (Windows) antes de qualquer alteração.
+- **Isolamento de falhas**: o erro em um repositório não interrompe os
+  demais; o relatório final mostra `[OK]`, `[AVISO]` ou `[ERRO]` por
+  item, com tempo de execução.
+- **Saída limpa**: cancelamento via `Ctrl+C` em qualquer prompt
+  ou `SIGINT` durante a execução.
+
+## Requisitos
+
+| Requisito       | Versão           | Observação                       |
+| --------------- | ---------------- | -------------------------------- |
+| Node.js         | >= 20            | Verificado no preflight          |
+| npm             | >= 10            | Gerenciador de pacotes fixo      |
+| Git             | qualquer recente | Precisa estar no `PATH`          |
+| PowerShell      | qualquer         | Somente Windows — `install.ps1`  |
+| Credenciais Git | —                | Acesso aos repositórios privados |
+
+## Instalação
+
+Clone este repositório e instale as dependências:
+
+```bash
+git clone https://github.com/EdgarSocrates98/forge-cli.git
+cd forge-cli
+npm install
+```
+
+Para rodar sem compilar:
+
+```bash
+npm run dev
+```
+
+Para compilar e usar como comando global:
+
+```bash
+npm run build
+npm link        # registra o binário `forge-cli`
+forge-cli       # em qualquer diretório
+```
+
+Alternativa sem npm global — o próprio CLI se registra no PATH do usuário
+(sem admin), copiando o bundle para `~/.forge-cli/bin`:
+
+```bash
+npm run build
+node dist/index.js self install  # Windows: forge-cli.cmd + PATH do usuário
+                               # Linux/macOS: shim sh + bloco nos profiles
+forge-cli self uninstall       # desfaz tudo (PATH, shims e bundle)
+```
+
+Após `self install`, abra um terminal novo — o PATH do usuário só é lido por
+processos novos. `forge-cli doctor` avisa quando o binário não está
+acessível no PATH.
+
+## Quickstart
+
+1. Instale o forge-cli (`npm run build && node dist/index.js self install` a partir do clone, ou `npm i -g theforge-cli` quando publicado).
+2. Abra um terminal novo e rode `forge-cli`.
+3. Escolha **Instalar Forjas**, selecione as Forjas desejadas e confirme.
+4. Use os comandos oficiais de cada Forja (a seção "próximos passos" do relatório lista os principais).
+
+Para atualizar o próprio CLI: `forge-cli self update` (npm global executa `npm i -g theforge-cli` com `--yes`; demais métodos mostram o passo manual).
+
+## Instalador nativo (perfil, escopo, componentes)
+
+```bash
+forge-cli install spark-forge-aws --profile recommended --scope project --components skills,agents        # plano (--dry-run)
+forge-cli install spark-forge-aws --profile recommended --scope project --components skills,agents --yes  # aplica
+```
+
+O forge-cli só delega ao `<cli> install` que a Forja documenta; Forjas sem
+instalador nativo (ex.: forge-portal) recebem um aviso, sem substituto
+silencioso. Veja [docs/capabilities.md](docs/capabilities.md).
+
+## Independência
+
+O forge-cli é uma conveniência opcional: nenhuma Forja depende dele e remover o CLI (`self uninstall`) não afeta Forjas já instaladas. Instalações feitas à mão são reconhecidas (`forge-cli status`) sem precisar reinstalar. Estes cenários estão cobertos em `tests/independence.test.ts`.
+
+## Comandos
+
+```bash
+forge-cli install api-forge platform-forge   # instala Forjas escolhidas
+forge-cli install                            # fluxo interativo
+forge-cli clone api-forge                    # só clona/sincroniza, sem scripts
+forge-cli status                             # estado local (clonado, versão, alterações)
+forge-cli update [--check]                   # atualiza (ou só verifica) Forjas clonadas
+forge-cli versions api-forge                 # revisão e tags
+forge-cli install api-forge --version 1.2.0  # fixa em tag/sha (checkout destacado)
+forge-cli pin|unpin|rollback api-forge       # fixação e retorno ao HEAD anterior
+forge-cli reinstall api-forge [--clean]      # mantém a revisão; --clean reclona com backup
+forge-cli uninstall api-forge [--yes]        # plano + backup de .env/configs
+forge-cli components [forjas]                # flags do instalador nativo por Forja
+forge-cli doctor [forjas] [--fix]            # diagnostica (ou repara) Forjas
+forge-cli install api-forge --offline        # só usa clone existente, sem rede
+forge-cli update api-forge --native           # também a operação nativa (--dry-run sem --yes)
+forge-cli uninstall api-forge --native --yes # desinstala nativamente e depois remove o clone
+forge-cli status --json                      # saída estruturada (também list, versions, components, doctor)
+forge-cli self install | self uninstall | self update
+forge-cli help
+```
+
+Segurança: scripts não rodam após falha de sync (`--run-after-sync-failure`
+libera) e repositórios de `forge-cli.repos.json` só executam scripts com
+`--trust-custom`. `--yes` não autoriza o instalador nativo a escrever sem
+que seja passado explicitamente.
+
+> `forge-cli install` agora instala Forjas; o registro no PATH passou a
+> ser `forge-cli self install`.
+
+## Uso
+
+Execute `npm run dev` (ou `forge-cli`, se instalado globalmente) e siga
+o fluxo interativo:
+
+1. **Banner e verificação de ambiente.** O CLI exibe o banner do Forge
+   e valida `git`, a versão do Node.js e o `powershell.exe` (no
+   Windows). Falhas encerram o processo antes de qualquer prompt.
+2. **Diretório de instalação.** Informe onde os repositórios serão
+   clonados. O padrão é `./forge-workspace`; o caminho é convertido
+   para absoluto e o diretório criado se não existir.
+3. **Seleção de repositórios.** Marque ou desmarque itens com `Espaço`.
+   Todos os oito vêm selecionados por padrão; ao menos um é obrigatório.
+4. **Confirmação.** Revise o resumo (destino e quantidade) e confirme.
+5. **Execução.** Para cada repositório, um spinner mostra a fase atual:
+   `Sincronizando`, `Provisionando .env` e `Executando script`.
+6. **Relatório final.** Status por repositório com tempo de execução e
+   totais agregados.
+
+Para cancelar em qualquer etapa, pressione `Ctrl+C`. O processo
+encerra de forma limpa (código `130` em `SIGINT`).
+
+## Repositórios do ecossistema
+
+| Repositório         | Descrição                        |
+| ------------------- | -------------------------------- |
+| `the-forge`         | Framework base e utilitários     |
+| `spark-forge-aws`   | Pipelines Spark para AWS         |
+| `spark-forge-azure` | Pipelines Spark para Azure       |
+| `platform-forge`    | Serviços e infra de plataforma   |
+| `api-forge`         | Backend central e APIs           |
+| `forge-doctor-api`  | API de diagnóstico e telemetria  |
+| `forge-doctor-data` | Pipeline de dados de diagnóstico |
+| `forge-portal`      | Frontend / Portal Web            |
+
+Todos os repositórios ficam na organização
+[`EdgarSocrates98`](https://github.com/EdgarSocrates98) no GitHub.
+
+## Provisionamento do `.env`
+
+Antes do script de instalação, cada repositório recebe um `.env`:
+
+| Condição              | Ação                          | Indicador no relatório                 |
+| --------------------- | ----------------------------- | -------------------------------------- |
+| `.env` já existe      | Nada — nunca sobrescreve      | `.env já existia`                      |
+| `.env.example` existe | Copiado para `.env`           | `.env criado a partir de .env.example` |
+| Nenhum dos dois       | Modelo com comentários criado | `.env criado (modelo vazio…)`          |
+
+Se o provisionamento falhar (por exemplo, permissão negada), o
+repositório é marcado como `[ERRO]` e o script de instalação **não**
+é executado para ele.
+
+## Status de execução
+
+| Status       | Significado                                        |
+| ------------ | -------------------------------------------------- |
+| ✅ `[OK]`    | Clonado/atualizado e script executado com sucesso  |
+| ⚠️ `[AVISO]` | Clonado, mas sem script de instalação para este SO |
+| ❌ `[ERRO]`  | Falha no clone/pull, no `.env` ou no script        |
+
+## Scripts do projeto
+
+| Comando             | Ação                                   |
+| ------------------- | -------------------------------------- |
+| `npm run dev`       | Executa o CLI via `tsx`, sem compilar  |
+| `npm run build`     | Compila `src/` para `dist/` via `tsup` |
+| `npm start`         | Executa `dist/index.js`                |
+| `npm test`          | Testes unitários via `vitest`          |
+| `npm run typecheck` | Verificação de tipos (`tsc --noEmit`)  |
+
+## Estrutura do projeto
+
+```text
+src/
+  index.ts           # despacho: args, menu, subcomando
+  cmd/               # implementação dos comandos (query, manage, run, batch, shared)
+  prompts.ts         # prompts: diretório, seleção, confirmação
+  menu.ts            # menu principal (TUI)
+  commands.ts        # resolução de subcomandos
+  safety.ts          # nomes/URLs seguros, symlinks, redação de segredos
+  git-revs.ts        # tags, checkout por ref, update --check
+  lifecycle.ts       # uninstall seguro, rollback
+  native-install.ts  # adaptador do instalador nativo (profile/scope/components)
+  status.ts          # estado local por Forja
+  self.ts            # self update por método de instalação
+  runner.ts          # pipeline por repositório (clone → .env → script)
+  env.ts             # provisionamento do .env
+  preflight.ts       # verificações de ambiente
+  report.ts          # relatório final
+  ui/
+    theme.ts         # paleta de cores e ícones (picocolors)
+    strings.ts       # todas as mensagens PT-BR
+  constants/
+    repos.ts         # catálogo dos 8 repositórios
+  utils/
+    system.ts        # caminhos, .git, scripts por SO, execução
+  types.ts           # tipos compartilhados
+tests/               # testes unitários (vitest)
+factory/             # fluxo spec-driven (Loop Factory)
+```
+
+## Documentação
+
+- [Arquitetura e decisões de design](docs/arquitetura.md)
+- [Matriz de capacidades das Forjas](docs/capabilities.md)
+- [Solução de problemas](docs/solucao-de-problemas.md)
+- [Como contribuir](CONTRIBUTING.md)
+- [Registro de mudanças](CHANGELOG.md)
+
+## Licença
+
+[MIT](LICENSE) © 2026 Edgar Sócrates Caria