theforge-cli 0.2.2 → 0.2.4

package/docs/installation.md

@@ -0,0 +1,157 @@
+# Guia de instalação por cenário
+
+Ciclo 12.1 (`lf-0015`–`lf-0019`). O objetivo é que a instalação de uma
+Forja **não dependa de um único método de aquisição**: PyPI, clone git,
+ZIP do GitHub, pasta copiada ou diretório sem `.git` são entradas
+válidas quando existe um método local compatível, funcional e
+autorizado. A ausência de `.git`, de PowerShell ou de um Python no PATH
+nunca bloqueia isoladamente a instalação.
+
+Toda recusa sai com código `FORGE-*`, causa e remédio — veja a tabela
+completa em [troubleshooting.md](troubleshooting.md). `forge doctor`
+diagnostica a instalação depois do fato; `forge env discover --json`
+mostra as rotas/shells/interpretadores que a máquina oferece **antes**
+de instalar.
+
+## Sumário dos cenários
+
+| #   | Cenário                         | Comando                                                 | Rota                                                |
+| --- | ------------------------------- | ------------------------------------------------------- | --------------------------------------------------- |
+| 1   | PyPI (recomendado)              | `forge-cli install <forja> --method registry`           | venv isolada em `~/.forge-cli/forges/`              |
+| 2   | Clone git                       | `forge-cli install <forja>`                             | clone + `install.sh`/`install.ps1`                  |
+| 3   | ZIP do GitHub                   | `forge-cli install ./forja-1.2.3`                       | detecção local + bootstrap no lugar                 |
+| 4   | Pasta copiada                   | `forge-cli install ./cópia`                             | idem — gitless é cidadão de 1ª classe               |
+| 5   | Diretório sem `.git`            | `forge-cli install ./dir`                               | idem                                                |
+| 6   | Windows + PowerShell            | `forge-cli install <forja>`                             | `install.ps1`/`setup.ps1` via powershell.exe → pwsh |
+| 7   | Windows sem PowerShell          | `forge-cli install <forja>` no Git Bash                 | `install.windows.sh` via Git Bash                   |
+| 8   | Python corporativo fora do PATH | `forge-cli install <alvo> --python C:\corp\python.exe`  | estágio explícito do pipeline                       |
+| 9   | Vários Pythons (Linux)          | `forge-cli install <alvo>` ou `--python`/`FORGE_PYTHON` | descoberta escolhe o mais novo compatível           |
+| 10  | Rede/permissão restrita         | `forge-cli install <forja> --method registry --offline` | wheelhouse/cache local; sem admin                   |
+
+## 1. PyPI — `install --method registry`
+
+```bash
+forge-cli install api-forge --method registry
+forge-cli install --all --method registry
+forge-cli registry                      # catálogo + o que está instalado
+```
+
+Cada Forja vai para `~/.forge-cli/forges/<nome>/` com
+`pip install <dist>==<versão>` pinado; o interpretador é o mais novo
+que satisfaz `requires_python`. Sem compatível, a instalação é recusada
+(`FORGE-PYTHON-INCOMPATIBLE`) antes de qualquer mutação.
+
+## 2. Clone git — `install <nome>`
+
+```bash
+forge-cli install api-forge platform-forge
+forge-cli install            # TUI guiada
+forge-cli install api-forge --version 1.2.0   # pin em tag/sha
+```
+
+Clona no workspace (`--dir`, padrão `./forge-workspace`), provisiona
+`.env` e roda o script do SO. Requer `git` no PATH e credenciais.
+
+## 3–5. Fonte local — `install <dir>` (ZIP, cópia, sem `.git`)
+
+```bash
+forge-cli install ./spark-forge-aws-main     # ZIP extraído do GitHub
+forge-cli install ~/minhas/forjas/api-forge  # pasta copiada / sem .git
+forge-cli install ./fonte --plan             # só classifica, zero escrita
+```
+
+O diretório é classificado por `forge/LocalForgeSourceDetection/v1` em
+oito estados (`GIT_REPOSITORY`, `GIT_WORKTREE`, `GITLESS_VALID_FORGE`,
+`GITLESS_PARTIAL_FORGE`, `UNKNOWN_DIRECTORY`, `CONFLICTING_IDENTITY`,
+`INVALID_MANIFEST`, `UNTRUSTED_SOURCE`) — detecção só por filesystem,
+sem spawn de git e sem rede. Fontes parciais (estrutura incompleta)
+exigem `--yes`. O bootstrap roda **no lugar**: nunca `git init`,
+`clone`, `pull` ou rede.
+
+O receipt registra `source_dir`, `is_git`, `manifest_valid`,
+`source_trust` (A/B/C), `integrity`, `execution_environment`,
+`managed_artifacts` e `source_files` — `forge status` e `forge doctor`
+reconhecem a instalação gitless normalmente.
+
+Persistência de ambiente: um `.env` existente na fonte **nunca** é
+sobrescrito — `.env.example` só é copiado quando `.env` está ausente
+(e um stub comentado é criado quando nem o exemplo existe). Exemplos
+de config (`*.example.*`) só são copiados quando o destino não existe;
+`.env.example` em si nunca é copiado pela regra genérica. Falha de
+escrita nessa etapa é recusa nomeada `FORGE-ENV-PERSISTENCE-FAILED`,
+antes de qualquer bootstrap.
+
+## 6. Windows + PowerShell
+
+Ordem de rota no Windows: `powershell.exe` (5.1) → `pwsh` (7+) → Git
+Bash. Com PowerShell presente a cadeia é `.ps1`
+(`setup.ps1`/`install.ps1`); a política de execução é contornada por
+`-ExecutionPolicy Bypass` no escopo do processo.
+
+## 7. Windows sem PowerShell — rota Git Bash
+
+Quando `powershell.exe`/`pwsh` estão ausentes ou bloqueados e o Git
+Bash executa, a rota é `.sh` com `install.windows.sh` primeiro
+(seguido de `setup.sh`/`install.sh`). O bash.exe precisa ser o do **Git
+for Windows** e responder a `-lc 'echo ok'` — WSL, Cygwin e MSYS2 são
+reportados pela descoberta mas **nunca** são rota nativa.
+
+```bash
+# dentro do Git Bash
+bash install.windows.sh            # instalador direto da Forja
+forge-cli env discover --json      # route.selected deve ser "git_bash"
+```
+
+Cenário coberto em CI como simulação (PATH mascarado no runner
+Windows) — o gate de hardware corporativo real é ação humana
+documentada no acceptance report.
+
+## 8. Python corporativo fora do PATH — `--python` / `FORGE_PYTHON`
+
+```bash
+forge-cli install ./api-forge --python "C:\Python311\python.exe"
+FORGE_PYTHON=/opt/python311/bin/python forge-cli install api-forge
+```
+
+`FORGE_PYTHON` (estágio 0) precede até `--python` (estágio 1). Depois
+vêm o launcher `py`, nomes de PATH, venvs, managers, locais de
+plataforma e caminhos convencionais — todo candidato é **executado**
+com `--version`; alias da Microsoft Store que não executa vira
+`store-stub` (nunca selecionado). Piso padrão `>=3.10`; um `forge.json`
+com campo `python` pode exigir mais.
+
+## 9. Vários Pythons no Linux
+
+A descoberta examina `python3.x` decrescentes e escolhe o mais novo que
+satisfaz o piso — um Python 3.13 no PATH vence um 3.10 mesmo sem flag.
+`forge env discover --json` lista todos os candidatos com
+`verdict`/`code` por item.
+
+## 10. Rede ou permissão restrita
+
+```bash
+forge-cli install api-forge --method registry --offline   # só cache local
+forge-cli env paths                                       # matriz de alvos de escrita
+forge-cli install <dir>                                   # fonte local: zero rede
+```
+
+- `--offline` resolve do wheelhouse (`~/.forge-cli/cache/wheels/`) e
+  metadados — artefato ausente = recusa honesta, nunca fingimento.
+- Nada de `sudo`/admin: alvos de escrita são os diretórios do usuário
+  (`env paths` mostra `home`, `bin`, `venvs`, `receipts`…); alvo
+  negado sai como `FORGE-INSTALL-PERMISSION-DENIED` com o fallback.
+- Fonte local (`install <dir>`) não toca rede por definição.
+
+## Ciclo de vida da fonte local
+
+| Operação     | Comando                            | Comportamento                                                                                                                               |
+| ------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Atualizar    | `forge-cli update <dir-mais-novo>` | reconcilia arquivos na fonte registrada (copia novos/alterados; remove só o que o receipt registrou e a fonte nova não traz)                |
+| Reparar      | `forge-cli reinstall <nome>`       | remove artefatos gerenciados registrados e re-executa o bootstrap no lugar                                                                  |
+| Desinstalar  | `forge-cli uninstall <nome> --yes` | remove **só** `managed_artifacts` (com backup dos arquivos em `~/.forge-cli/backups/`); a fonte e os arquivos do usuário nunca são apagados |
+| Diagnosticar | `forge status` / `forge doctor`    | receipt local aparece como `install_method: local`; fonte ausente vira `drifted`, nunca erro                                                |
+
+`update <nome>` (pelo nome) é recusado para fontes sem git com
+`FORGE-SOURCE-GITLESS` — a semântica de `pull` não existe; aponte o
+diretório-fonte mais novo. `--method git` numa fonte sem `.git` recebe
+a mesma recusa antes de instalar.

package/docs/solucao-de-problemas.md

@@ -1,17 +1,22 @@
 # Solução de problemas
 
-Falhas comuns do forge-cli e como resolver cada uma.
+Falhas comuns do forge-cli e como resolver cada uma. Para os códigos de
+recusa `FORGE-*` (fonte local, shells, Python, permissões), a tabela
+completa está em [troubleshooting.md](troubleshooting.md) — cada código
+carrega causa e remédio acionável. O guia por cenário de instalação
+(PyPI, git, ZIP, Git Bash, Python fora do PATH, offline) está em
+[installation.md](installation.md).
 
 ## O preflight falha
 
 O preflight roda antes de qualquer prompt e encerra com código `1`
 quando algo falta:
 
-| Falha                         | Causa                               | Correção                                               |
-| ----------------------------- | ----------------------------------- | ------------------------------------------------------ |
-| `git` indisponível            | Git não instalado ou fora do `PATH` | Instale o Git e abra um terminal novo                  |
-| `Node.js >= 20` falha         | Versão antiga                       | Atualize via [nodejs.org](https://nodejs.org) ou `nvm` |
-| `powershell.exe` indisponível | Somente Windows; fora do `PATH`     | Reinstale o PowerShell ou ajuste o `PATH`              |
+| Falha                             | Causa                                               | Correção                                                                                        |
+| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `git` indisponível                | Git não instalado ou fora do `PATH`                 | Instale o Git e abra um terminal novo                                                           |
+| `Node.js >= 20` falha             | Versão antiga                                       | Atualize via [nodejs.org](https://nodejs.org) ou `nvm`                                          |
+| shell de instalação ausente (Win) | `powershell.exe`/`pwsh` fora do PATH e sem Git Bash | Instale Git for Windows (o Git Bash cobre a rota `install.windows.sh`) ou habilite o PowerShell |
 
 ## Falha no clone/pull (`[ERRO]`)
 
@@ -33,10 +38,12 @@ quando algo falta:
 
 ## O script de instalação falha
 
-- **Windows**: o CLI executa
-  `powershell.exe -NoProfile -ExecutionPolicy Bypass -File install.ps1`.
-  Se a política de execução estiver restrita demais ou o PowerShell for
-  o Core (`pwsh`), ajuste o script ou o ambiente.
+- **Windows**: o CLI executa `.ps1` via `powershell.exe -NoProfile
+-ExecutionPolicy Bypass` (ou `pwsh` quando o 5.1 está ausente). Sem
+  nenhum PowerShell, o Git Bash executa `install.windows.sh`/`setup.sh`
+  — a rota é escolhida pelo que executa, não pelo PATH declarado. Se a
+  política de execução estiver restrita demais, ajuste o script ou o
+  ambiente (`FORGE-SHELL-UNAVAILABLE`).
 - **Linux/macOS**: o CLI executa `chmod +x install.sh && ./install.sh`.
   Confirme que o script é válido para o seu shell.
 - **Sem script para o SO**: o repositório sai como `[AVISO]`, não

package/docs/troubleshooting.md

@@ -0,0 +1,62 @@
+# Códigos `FORGE-*` — taxonomia de recusa (ciclo 12.1)
+
+Toda recusa nomeada sai com código estável + causa + remédio acionável,
+no texto do erro e no `--json` (`results[].code`/`cause`/`remedy`).
+Contrato de exit code: `2` = recusa nomeada (nada foi escrito),
+`1` = falha operacional (script/setup quebrou depois de autorizado —
+sem código inventado), `0` = ok. O mesmo código significa a mesma coisa
+em POSIX e Windows; os remédios abaixo cobrem os dois.
+
+## Códigos do CLI (`src/errors.ts`)
+
+| Código                              | Causa                                                                                                                                                                                              | Remédio                                                                                                                                                                                                      |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `FORGE-SOURCE-NOT-FOUND`            | Caminho inexistente, não é diretório ou não tem nenhum marcador de Forja (sem `.git` e sem `forge.json`); também: update/repair/uninstall sem receipt registrado, ou `source_dir` registrado sumiu | Verifique o caminho; instale pelo catálogo (`install <nome>`/`--method registry`); se a fonte registrada foi movida, `uninstall <nome>` limpa o registro                                                     |
+| `FORGE-SOURCE-GITLESS`              | A operação exige git (`--method git`, `update <nome>` por nome, `clone`) mas a fonte não tem `.git`; ou fonte parcial instalada sem confirmação                                                    | Remova `--method git`, passe o diretório ao `update` (`update <dir-novo>`) ou confirme fonte parcial com `--yes`                                                                                             |
+| `FORGE-SOURCE-INVALID`              | `forge.json` malformado/ausente na rota local, sem script executável e sem fallback `scripts/forge_bootstrap.py`, fonte não confiável (symlink/junction), ou ação registry-only num receipt local  | Corrija `forge.json` (JSON válido + `forge_id`), forneça `install.sh`/`setup.sh`/`install.windows.sh` ou aponte o diretório real; para receipt local use a rota sem `--method`                               |
+| `FORGE-SOURCE-CONFLICT`             | Identidade contraditória: nome do diretório/cli aponta uma Forja do catálogo diferente do `forge_id` declarado; ou receipt PyPI pré-existente para o mesmo `forge_id`                              | Corrija `forge.json` ou aponte o diretório certo; para reinstalar por fonte local uma Forja do PyPI, `uninstall --method registry <nome>` primeiro                                                           |
+| `FORGE-INSTALL-VERIFICATION-FAILED` | Bootstrap executou mas o verify pós-install (`<cli> --help`) saiu não-zero — instalação registrada, entrada quebrada                                                                               | Rode o cli manualmente dentro da fonte para ver o erro; o receipt já está gravado para diagnóstico                                                                                                           |
+| `FORGE-SHELL-NOT-FOUND`             | Windows sem nenhuma shell de instalação utilizável: `powershell.exe`/`pwsh` ausentes e Git Bash inexistente                                                                                        | Instale PowerShell 7+ (`winget install Microsoft.PowerShell`), habilite o `powershell.exe` 5.1 ou instale Git for Windows (o Git Bash vira a rota de `install.windows.sh`). WSL nunca substitui shell nativo |
+| `FORGE-SHELL-UNAVAILABLE`           | Shell candidata existe no disco mas não executa (política/AppLocker/WDAC bloqueando ou instalação quebrada)                                                                                        | Verifique `Get-ExecutionPolicy` e a política corporativa, ou reinstale PowerShell 7+/Git for Windows                                                                                                         |
+| `FORGE-INSTALL-PERMISSION-DENIED`   | Alvo de escrita resolvido nega permissão (home, bin, venvs, receipts…)                                                                                                                             | Rode `forge-cli env paths` para ver a matriz de alvos e o fallback concreto; ajuste permissões ou aponte outro diretório                                                                                     |
+| `FORGE-ENV-PERSISTENCE-FAILED`      | Provisionamento de ambiente falhou na escrita (`.env`/configs de exemplo) — diretório da fonte ou alvo sem permissão de escrita                                                                    | Dê permissão de escrita no diretório da fonte e reexecute; o instalador grava `.env` e copia `*.example.*` antes do bootstrap                                                                                |
+| `FORGE-PYTHON-NOT-FOUND`            | Pipeline não achou nenhum interpretador (ou só aliases da Microsoft Store, que não executam)                                                                                                       | Instale Python ≥3.10 ou aponte explicitamente com `--python <exe>`/`FORGE_PYTHON`                                                                                                                            |
+| `FORGE-PYTHON-INCOMPATIBLE`         | Candidatos executaram mas todos abaixo do piso (`requires_python` do release ou `python` do `forge.json` — piso padrão ≥3.10)                                                                      | Aponte um interpretador compatível com `--python`/`FORGE_PYTHON`                                                                                                                                             |
+| `FORGE-PYTHON-UNEXECUTABLE`         | Candidato existe mas `--version` falha, expira ou não parseia (stub da Store, exe quebrado, shim morto)                                                                                            | Teste `<exe> --version` manualmente; aponte outro interpretador com `--python`/`FORGE_PYTHON`                                                                                                                |
+
+## Códigos do instalador compartilhado (`scripts/forge_bootstrap.py` + `install.windows.sh`)
+
+Emitidos pela camada Python/bash vendored nas Forjas — mesma
+convenção: código no stderr/JSON e remédio explícito.
+
+| Código                              | Causa                                                                                | Remédio                                                                |
+| ----------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| `FORGE-INSTALL-NO-CONFIG`           | `forge.json` ausente no diretório onde o bootstrap rodou                             | Rode dentro de um checkout/fonte de Forja com `forge.json`             |
+| `FORGE-INSTALL-BAD-CONFIG`          | `forge.json` inválido ou faltando chaves                                             | Corrija o manifesto                                                    |
+| `FORGE-INSTALL-DIST-INVALID`        | `--dist` fora da whitelist do instalador                                             | Use a distribuição publicada da Forja                                  |
+| `FORGE-INSTALL-DIST-URL`            | `--dist-url` fora do esquema/host permitido                                          | Aponte uma URL `https://` autorizada                                   |
+| `FORGE-INSTALL-DIST-MISMATCH`       | Dist/url divergem do esperado pelo manifesto                                         | Alinhe dist e url com a Forja instalada                                |
+| `FORGE-INSTALL-MODE-CONFLICT`       | Combinação inválida de flags de modo                                                 | Rode com um modo só (`--help` lista)                                   |
+| `FORGE-INSTALL-PYTHON-INCOMPATIBLE` | Interpretador abaixo do `requires-python` da Forja                                   | Aponte Python compatível na flag/`FORGE_PYTHON`                        |
+| `FORGE-INSTALL-VENV-FAILED`         | `python -m venv` falhou ou a venv ficou incompleta                                   | Verifique `python3-venv`/`ensurepip` instalados e permissão de escrita |
+| `FORGE-INSTALL-RUNTIME-FAILED`      | Falha de runtime do bootstrap (pip/wheel interno)                                    | Veja o log impresso; rede offline exige wheelhouse                     |
+| `FORGE-INSTALL-CLI-MISSING`         | Binário `<cli>` ausente no `bin/` da venv após o install                             | Reinstale; entry-point do pacote quebrado                              |
+| `FORGE-INSTALL-VERIFY-FAILED`       | Smoke pós-install falhou (equivalente ao `FORGE-INSTALL-VERIFICATION-FAILED` do CLI) | Rode o binário da venv manualmente                                     |
+| `FORGE-INSTALL-BOOTSTRAP-FAILED`    | `install.windows.sh` repassou falha não-zero do bootstrap                            | Veja o log `forge-install-*.log` ao lado da fonte                      |
+| `FORGE-ENV-PERSISTENCE-FAILED`      | `--persist-env` não conseguiu gravar PATH/perfil do usuário                          | Ajuste permissões do perfil ou rode sem `--persist-env`                |
+
+## Recusas de pipeline sem script
+
+Quando a fonte não tem script executável **e** o fallback
+`forge_bootstrap.py` falhou por descoberta de Python, o código
+`FORGE-PYTHON-*` da descoberta é propagado no lugar de
+`FORGE-SOURCE-INVALID` — a causa real é o interpretador, não a fonte.
+
+## Diagnóstico rápido
+
+```bash
+forge env discover --json   # shells, rota escolhida, pythons sondados
+forge env paths             # alvos de escrita + fallbacks
+forge doctor --json         # checks por domínio (fontes locais incl.)
+forge status --json         # estado por Forja (receipts locais incl.)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theforge-cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "CLI interativa para clonar e configurar o ecossistema Forge",
   "type": "module",
   "bin": {