theforge-cli 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,7 +3,439 @@
 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]
+## [0.2.0] - 2026-10-17
+
+### Cycle 11.1 — hardening de produção, MCP real e Trusted Publishing
+
+#### P0-001 — npm Trusted Publishing (OIDC)
+
+- `publish-npm.yml` reescrito: `workflow_dispatch(version, tag?)` →
+  job `validate` (gates completos + `npm pack --dry-run` + release
+  gate) → job `publish` (`environment: npm`, `id-token: write`,
+  checkout pinado no SHA validado — sem TOCTOU), provenance e
+  smoke pós-publish (registry check + install limpo + `--help`).
+- `scripts/release/verify-version.mjs`: recusas nomeadas —
+  `version-invalid`, `version-mismatch`, `version-exists`,
+  `tag-missing`, `tag-mismatch`, `repo-url`, `license-missing`.
+- `docs/releasing/npm-trusted-publishing.md`: setup do publisher,
+  environment, gates, troubleshooting e recovery.
+- Setup externo (publisher no npmjs.com + environment `npm` com
+  aprovação) é ação do mantenedor — `BLOCKED_EXTERNAL` até então.
+
+#### P0-002 — pureza de `--plan`/`--check`/`--dry-run`
+
+- `resolveRelease` ganha `ephemeral`: em plano, o fetch PyPI pode
+  acontecer mas **nada persiste** — nem o cache TTL de metadados
+  (`resolveRelease` não chama mais `writeCache` sob ephemeral).
+- `tests/plan-purity.test.ts`: snapshot sha256 da árvore do home
+  antes/depois — `install --plan`, `update --check` e uninstall
+  não-TTY sem `--yes` (needsYes) produzem zero mutação observável.
+
+#### P1-002 — verificação MCP de protocolo real
+
+- `src/mcp/handshake.ts`: probe stdio JSON-RPC — spawn (argv array,
+  sem shell) → `initialize` → `notifications/initialized` →
+  `tools/list` → kill. Níveis `MCP_INITIALIZED`/`TOOLS_DISCOVERED`;
+  timeouts por etapa e global, caps de tamanho/contagem de linhas,
+  `tools/call` nunca executado.
+- `forge-cli mcp --verify` agora roda o probe real (não mais
+  `--version`): JSON reporta `probe.{ok,levels,tools,server,protocol,
+error}` com erros nomeados (`stdout-non-json`, `server-exit`,
+  `initialize-invalid`, `tools-list-invalid`, `timeout`, `spawn-failed`).
+
+#### P1-001 — registry-first na experiência
+
+- README: instalação npm primeiro (sem clone), contribuidor via
+  clone depois; seção PyPI marcada como método recomendado
+  (registry-first, não registry-only).
+
+### Cycle 11 — instalação registry-first (PyPI)
+
+#### Wave 7 — performance (números medidos, não inventados)
+
+- `scripts/bench.mjs`: mede startup (`--help`), `status`, `registry`,
+  resolve `--plan` (rede), install frio, reinstall e `update --check`
+  (cache). Mediana de N runs (`--runs`), JSON
+  `forge-cli/BenchReport/v1` em stdout, `FORGE_CLI_HOME` hermético.
+- Medido local (Node 24, Linux, 3 runs): `--help` ~259ms,
+  `status` ~72ms, `registry` ~67ms, `resolve --plan` ~290ms (PyPI
+  online), install frio ~3.2s e reinstall ~3.5s (venv+pip dominam —
+  fora do nosso controle), `update --check` com cache ~217ms.
+- **`FORGE_CLI_HOME`**: novo env override para o home de estado
+  (`~/.forge-cli`) — bench/testes/containers rodam isolados sem tocar
+  o estado real. Não afeta detecção de hosts (esses ficam no home real).
+
+#### Wave 8 — supply chain / hardening
+
+- **Retry com backoff no PyPI**: `fetchWithRetry` — 429/5xx e erros de
+  rede retentam 2x (250ms→500ms); 404 e respostas definitivas retornam
+  imediato. Retry nunca mascara "não existe".
+- **`receipt.provenance`**: `{registry:'pypi.org', file, url,
+resolvedVia:'pypi'|'offline-cache'}` — proveniência auditável do
+  artefato instalado junto ao `verifiedHash`.
+- **Permissões do state dir**: `~/.forge-cli` e `forges/` recebem
+  `chmod 0700` no POSIX (Windows: ACL do perfil, chmod é no-op).
+
+#### Wave 4 — hosts/MCP registry-aware
+
+- **`forge-cli mcp [forja…]`**: resolve o argv MCP por Forja e reporta
+  presença do binário. Fonte: `forge.json` do clone, ou — sem clone —
+  receipt registry + template `mcp` do catálogo (`{bin}` → bin da venv,
+  `{binDir}/x` → script irmão; `.exe` no Windows). `--verify` roda
+  `<argv[0]> --version` como handshake mínimo. `--json` emit
+  `{forge, mcp_command, binPresent, handshake?}` por item. Forja sem
+  `mcp_command` honesto (ex.: the-forge) sai `ok:false`, nunca inventa.
+- **`hosts plan|register|validate|rollback` sem clone**: `forgeDescriptor`
+  cai para o receipt + catálogo quando o manifest não está no
+  workspace — `hosts register claude api-forge` numa instalação
+  registry grava `mcpServers['api-forge'].command` apontando para o
+  `apiforge-mcp` da venv. Backup/rollback/`--yes` inalterados.
+- Catálogo: campo `mcp` por Forja espelhando o `mcp_command` de cada
+  `forge.json` (api-forge `apiforge-mcp`, platform-forge
+  `platformforge-mcp`, doctors `[bin] mcp`, spark-forge `[bin] mcp serve`).
+- `CliOptions.verify` + flag `--verify` registrada (parser é strict).
+
+#### Wave 3 — lifecycle registry
+
+- **`update --method registry`**: resolve a mais nova no PyPI, compara
+  com o receipt e reinstala limpo quando há versão nova. `--check`/
+  `--plan` mostram o plano sem mutar; `--ref <ver>` é override pontual
+  (não cria nem remove pin). Versões anteriores são empilhadas em
+  `receipt.history` — insumo do rollback.
+- **`reinstall --method registry`**: reinstala a mesma versão do
+  receipt (reparo de drift — venv apagada mas state presente recria).
+  Preserva `pinned` e `history` — reinstall não é lifecycle de versão.
+- **`rollback --method registry`**: desempilha `history.at(-1)` e
+  empilha a versão abandonada — rollback de rollback retorna à versão
+  original. Sem histórico → recusa honesta (`rollbackNoPrevious`), exit 1.
+- **`pin`/`unpin --method registry`**: trava/remove a versão instalada
+  no state; `update` respeita (`skipped: fixada em <ver>`).
+- **Ghost-forge no lifecycle**: Forja removida do catálogo mas com
+  receipt continua atualizável/reinstalável — `ghostEntry()` deriva
+  dist/bin do receipt e o piso Python do interpretador que a instalou.
+- **Contrato uniforme**: `isSafeRepoName`/`resolveInside` nos mesmos
+  pontos do uninstall; flags git ignoradas avisam também no lifecycle;
+  `update` com todos os alvos não-instalados sai 1 (nada aconteceu);
+  confirmação interativa só em TTY duplo (automação segue com `--yes`).
+
+#### Wave 2 — TUI registry + delegação nativa (fase 2)
+
+- **Menu guiado `--method registry`**: `shouldShowMenu` não exclui mais
+  o método — `menuItemsFor` filtra o menu para os verbos suportados
+  (install/update/reinstall/uninstall/status/exit). `status` mapeia
+  para `forge-cli registry` (receipts). Install escolhe no catálogo
+  PyPI com hint de dist+piso Python; lifecycle escolhe nas instaladas.
+- **Delegação ao instalador nativo** (`delegateNative`): `--native` ou
+  qualquer flag de fase 2 (`--profile/--scope/--components/--host/
+--gateway-profile`) roda `<bin> install` **pelo bin da venv
+  verificada** — nunca um shim global. Sem `--yes` roda `--dry-run`
+  (default-deny). `{python} scripts/...` (forge-doctor-api) é skip
+  honesto — o script vive no repositório, não na wheel.
+- **Native em lifecycle**: update/reinstall rodam a op `update`
+  documentada; `uninstall --native` roda `ops.uninstall` **antes** de
+  remover a venv. Tudo gravado em `receipt.native` (argv, ran, dryRun,
+  exitCode, skipped, ignored).
+- **Validação fail-fast**: `--profile/--scope/--components/--host/
+--gateway-profile` inválidos recusam antes de gastar rede (exit 1),
+  mesmo contrato do fluxo git. Flags saem de REGISTRY_IGNORED_FLAGS —
+  agora são honradas.
+- **`.env` preservado**: instalações registry vivem em venvs isoladas
+  sob `~/.forge-cli/` — nunca tocam `.env` de projetos do usuário.
+
+#### Corrigido após revisão (7ª rodada)
+
+- **Uninstall não-TTY sem `--yes` (crítico)**: `uninstall --method
+registry` pendurava em `confirm()` com stdin não-TTY (CI, pipes,
+  `--json --report` em automação). Agora recusa limpa — imprime
+  `needsYes`, grava o relatório se `--report` e sai 0, mesmo contrato
+  do fluxo git. Verificado real: `uninstall < /dev/null` → exit 0.
+- **`state.json` com valores não-objeto não derruba**: `{"forges":
+{"api-forge":"garbage"}}` é filtrado em `loadForgeState`; `registry`,
+  `status` e `list` não crasham (antes `TypeError` em `inst.verify.ok`)
+  — verificado real com o payload exato da revisão.
+- **Own-property no state**: `state.forges[name]` via `Object.hasOwn` —
+  `uninstall constructor`/`toString` sai 2 como desconhecido em vez de
+  casar membros do `Object.prototype` (a mesma classe do review-9, no
+  resolver — agora também no state).
+- **Recusa antes da resolução**: venv existente sem `--clean` falha
+  `already-installed` antes de gastar a chamada PyPI (fail fast,
+  inclusive offline).
+- **`--ref` pós-dedup**: `install api-forge apiforge-af --ref` é uma só
+  Forja (dedup por alias na validação do dispatcher).
+- **Confirmação mostra a versão resolvida**: o note de confirmação do
+  install interativo exibe `dist==versão` real (resolução antes do
+  confirm usa o cache no install seguinte — sem rede duplicada).
+- **Piso composto**: `minPython` do catálogo compõe com
+  `requires_python` (max implícito) — release que alargue o spec para
+  baixo do piso da forge-cli não habilita interpretadores sem suporte.
+- **`binPresent` estruturado**: `forge-cli registry --json` emite
+  `binPresent: boolean` em vez de embutir "(ausente)" no campo `bin`.
+- **`mergeRegistryPhase` tolerante**: own-property + campos checados —
+  receipt sem `verify`/`bin` não derruba o `status`/`list`.
+
+#### Corrigido após revisão (6ª rodada)
+
+- **Path traversal no uninstall (bloqueio)**: `name`/`dist` vindos do
+  `state.json`/receipt (dado não confiável — entrada fora do catálogo é
+  desinstalável por design) agora passam por `isSafeRepoName` +
+  `resolveInside`, a mesma convenção do `safety.ts` para caminhos
+  destrutivos. Nome inseguro = recusa nomeada com exit 2, nunca chega
+  ao `rmSync`; `dist` maliciosa só impede a limpeza do wheel cache
+  (venv+state ainda saem).
+- **Pin não-exato**: `--version 0.1` casa a chave `0.1.0` do PyPI por
+  equivalência parseada (PEP 440 zero-padding — o pip aceita `==0.1`).
+- **Confirmação interativa no install**: TTY + sem `--yes` mostra o
+  plano (`confirmRun`) antes de instalar, mesmo contrato do fluxo git;
+  `--json`/pipes/`--yes` seguem sem perguntar.
+- **`requires_python` autoritativo**: o piso `minPython` do catálogo só
+  se aplica quando os metadados do PyPI não declaram spec — o release
+  pode alargar o suporte sem depender de atualização do catálogo.
+- **`info.requires_python` escopado**: o campo descreve a release mais
+  nova; como fallback só vale quando a versão resolvida é ela (um pin
+  antigo não recebe o spec novo por engano).
+- **Cache e leitura defensivos**: `writeCache` atômico; cap de 16 MiB
+  aplicado antes de bufar o corpo (content-length + cancel do stream);
+  `state` com `forges: []` tratado como vazio.
+- **Quarentena em hash-mismatch**: artefato divergente é renomeado para
+  `.rejected` — preserva evidência, desbloqueia o retry e nunca é
+  selecionável pelo `--find-links` (extensão fora de `.whl`/`.tar.gz`).
+- **stderr redacted**: detalhes de erro de subprocesso passam por
+  `redactSecrets` — credenciais de `PIP_INDEX_URL` não vazam no stdout
+  JSON, no `--report` nem no log humano.
+
+#### Corrigido após revisão (5ª rodada)
+
+- **Dedupe pós-normalização**: `install api-forge apiforge-af` (nome +
+  alias) não falha mais com `already-installed` espúrio; uninstall
+  planeja uma única remoção.
+- **`status` honesto sob drift**: receipt registry com venv/bin ausente
+  vira `drifted` + "(bin ausente)" (antes marcava `installed` só pelo
+  state). `forge-cli registry` e `status` agora concordam.
+- **`--report` honrado**: escreve o documento JSON no arquivo (mesmo
+  contrato do fluxo git) em vez de só desviar o modo de saída;
+  `--json` sozinho continua emitindo no stdout.
+- **Flags ignoradas no uninstall**: `--dir`/`--profile`/etc. agora
+  avisam no uninstall também (antes só no install).
+- **Uninstall completo**: remove venv + `cache/wheels/<dist>` + state —
+  reclaim de disco; Forja fora do catálogo mas presente no state
+  continua desinstalável (entrada removida do catálogo não trava).
+- **Escritas atômicas**: `state.json` e `install.json` usam
+  `writeFileAtomic` (convenção do codebase) — kill no meio não corrompe.
+- **Sem dir órfão**: falha de install remove `forges/<nome>/` vazio.
+- **`--find-links` só no offline**: online as deps resolvem no índice —
+  wheel cache não compete desnecessariamente. Limite documentado:
+  offline, deps transitivas resolvem por nome sem pin de hash.
+- **Cache não envenenável**: payload 200 sem `releases` não sobrescreve
+  cache sadio — cai no cache ou falha `malformed`.
+- **Menu sem dead-end**: `--method registry` sozinho não abre o menu
+  interativo (que só roteava o fluxo git) — recusa limpa no dispatcher.
+- **`--method git` em comandos alheios**: agora avisa em vez de engolir
+  (ex.: `status --method git`).
+- **pip sem prompts**: `--no-input` em download/install; timeout do
+  subprocesso preserva o stderr real; payload PyPI tem cap de 16 MiB;
+  `available` do `version-not-found` vem ordenado.
+- **Banner do plano honesto**: "venv e estado não alterados" (o cache
+  de metadados pode ser atualizado — mesmo modelo de `update --check`).
+- Docs: `arquitetura.md` e `capabilities.md` descrevem o método
+  registry; decisões registradas como diferidas — `--python`
+  selecionável (§4.7), pipx/uv (§4.6), canal rc/beta (§4.1), lock de
+  state.json entre processos concorrentes.
+
+#### Corrigido após revisão (4ª rodada)
+
+- **Membership own-property**: `--version toString` (ou qualquer membro
+  do prototype) não é mais tratado como release existente — `plan`
+  chegava a certificar `apiforge-af==toString` como instalável.
+- **Instalação por artefato verificado**: o pip recebe o caminho local
+  da wheel/sdist com sha256 conferido — um arquivo plantado no wheel
+  cache com nome da dist nunca é escolhido por resolução de nome.
+  Sem artefato verificável → `hash-mismatch`, não instala. (Limite
+  honesto: dependências transitivas resolvem por nome em
+  `--find-links`; só o artefato da dist é vinculado por hash.)
+- **Reinstall sem `--clean`** recusa com `already-installed` — antes
+  `python -m venv` recriava sobre a venv boa e uma falha posterior a
+  destruía com o state intacto.
+- **`--report`/`--verbose`**: label correto (`--report`, não
+  `--report-path`) e `--verbose` entra na lista de avisados.
+- **Exit code consistente**: uninstall com nome desconhecido sai 2 em
+  modo humano também (antes só `--json` retornava erro).
+- **Cache TTL robusto a clock skew**: `fetchedAt` futuro conta como
+  stale, não como eternamente fresh.
+
+#### Corrigido após revisão (3ª rodada)
+
+- **PEP 440**: `XaN.postM` agora compara `post` dentro da fase de
+  pre-release — antes `1.0a1.post1` empatava com `1.0a1` e `!=`
+  avaliava errado.
+- **Alias de dist normalizado**: `registry apiforge-af` filtra a linha
+  certa e `uninstall --method registry apiforge-af` resolve o estado
+  pelo nome canônico — antes passavam validação e produziam saída
+  vazia/`não instalado` espúrio.
+- **`--clean` limpa o `state.json`** junto com venv/receipt — falha
+  posterior não deixa versão antiga registrada sem artefatos.
+- **subprocessos com timeout** (venv/download/pip/verify, 5 min
+  default) — antes só o fetch era limitado.
+- `selectInterpreter` ordena internamente (não depende do chamador);
+  `checkDistHashes` verifica **todos** os artefatos presentes;
+  `--version vX.Y.Z` aceita prefixo `v` no método registry.
+
+#### Corrigido após revisão (dispatch + integridade, 2ª rodada)
+
+- **`--plan`/`--dry-run`/`--check` honrados no registry**: resolvem e
+  mostram o plano (dist==versão, interpretador, venv, wheel cache) sem
+  criar venv, baixar artefatos ou gravar estado — antes executavam uma
+  instalação real.
+- **`--method registry` recusado no topo do dispatch** (`versions`,
+  `status`, `list`, `self update`, `doctor`, …) — antes só
+  `update`/`clone`/`reinstall`/`rollback`/`pin`/`unpin` alcançavam o
+  check e o resto executava o fluxo git.
+- **`--json` limpo nos caminhos de erro/aviso**: nomes desconhecidos,
+  skips de uninstall e a exigência de `--yes` emitem JSON estruturado
+  (`error`, `planned`, `skipped`, `warnings`) — antes logs humanos
+  poluíam stdout e quebravam `JSON.parse`.
+- **Flags ignoradas cobertas por completo**: `--skip-scripts`,
+  `--shallow`, `--fix`, `--rollback`, `--gateway-profile`,
+  `--trust-custom`, `--run-after-sync-failure`, `--report`,
+  `--only-changed` agora avisam também; `--clean` é honrado (recria a
+  venv) e `--check` funciona como plano.
+- **HTTP 5xx/429 do PyPI cai no cache local** (antes só exceções de
+  transporte); sem cache continua falhando honestamente.
+- **`--offline` verifica sha256 do wheel cacheado** contra o digest do
+  PyPI — cache adulterado aborta com `hash-mismatch`.
+- **Interpretador pré-release** só é escolhido quando nenhum estável
+  satisfaz `requires_python` (alinha com `packaging`).
+- **`distArtifactFiles`** usa prefixo normalizado com separador —
+  `dist_extra-…` não colide e sdists legados com `-` são encontrados.
+- **Ordenação PEP 440**: `XaN.devM`/`X.postN.devM` ordenam antes do
+  mesmo marco sem `.dev` (e branch morto removido).
+- **`registry <nome>`** filtra o catálogo; nome fora do catálogo →
+  erro 2.
+- **Pós-instalação** mostra o caminho do binário instalado (venv
+  isolada — PATH é decisão do usuário).
+
+#### Corrigido após revisão (dispatch + integridade)
+
+- **`--ref`/`--version` em multi-Forja** agora recusa como no fluxo git
+  (`errRefNeedsOne`) — antes aplicava o mesmo pin a todas as Forjas.
+- **`uninstall --method registry`**: dispatch movido para antes do
+  branch legado (sem nomes não executa mais a remoção do PATH),
+  `--all`/`--only` resolvem o conjunto instalado, e a remoção segue a
+  convenção destrutiva do repo — plano visível + confirmação/`--yes`.
+- **`--method registry` em comandos não suportados** (`update`, `clone`,
+  `reinstall`, `rollback`, …) é recusado em vez de cair no fluxo git.
+- **Offline real**: instalação online baixa artefatos para
+  `cache/wheels/<dist>/`; `--offline` instala com
+  `--no-index --find-links` e recusa com o artefato faltante nomeado
+  (nunca finge instalar sem rede).
+- **Integridade**: sha256 do artefato da dist é conferido byte a byte
+  após o download e gravado como `verifiedHash` no receipt; divergência
+  aborta antes do pip.
+- **Yanked/empty releases** não entram na escolha automática
+  (PEP 592); pin explícito instala e marca `yanked` no receipt.
+- **`status`** mostra Forjas instaladas via registry (fase
+  `installed`, `pypi dist==ver`) em vez de `not-installed`.
+- **`registry`** marca `(verify falhou)` em installs que não passaram
+  no verify; `--json` expõe `verifyOk`.
+- **`--json` no install/uninstall registry** emite JSON limpo (banner,
+  spinner e logs suprimidos); flags do fluxo git ignoradas viram aviso
+  explícito (`--dir`, `--profile`, `--scope`, `--components`,
+  `--host`, `--native`, `--skip-verify`, `--timeout`, `--jobs`,
+  `--retry-failed`).
+- **`requires_python` por arquivo**: prefere o da wheel (o que o pip
+  instala) ao do sdist/`info`.
+- **Especificador fora do subconjunto** (`===`, `~=X`, wildcard com
+  operador errado) vira `specifier-unknown`, não `python-incompatible`.
+- **Interpretador pré-release** (`Python 3.14.0a1`) parseia com sufixo.
+- **`state.json` corrompido** é preservado em `.corrupt` antes de ser
+  ignorado — nunca clobber silencioso.
+- **Venv órfã** removida em falha de venv/download/pip.
+- **Pisos do catálogo** corrigidos para o `requires_python` real
+  publicado (`apiforge-af` ≥3.12, doctors ≥3.11).
+
+#### Added
+
+- **`install --method registry`**: instala Forjas direto do PyPI sem
+  exigir clone do repositório nem o The Forge instalado. Cada Forja vai
+  para uma venv isolada em `~/.forge-cli/forges/<nome>/`, com
+  `pip install <dist>==<versão>` pinado e verify do console script.
+- **`forge-cli registry`**: lista o catálogo PyPI (7 dists), a versão
+  instalada e o binário de cada Forja; `--json` exporta.
+- **`uninstall --method registry`**: remove a venv e o receipt de uma
+  Forja instalada via registry.
+- **Resolver PyPI** (`src/registry/`): consulta o índice JSON do PyPI,
+  escolhe a estável mais nova (pré-releases ignoradas), honra
+  `--version`/`--ref` como pin e registra `source` no receipt
+  (`pinned|latest-stable|cache`).
+- **Compatibilidade Python pré-install**: `requires_python` do release é
+  avaliado por um subconjunto PEP 440 (`~=`, `==`/`!=` com `.*`, `>=`,
+  `>`, `<=`, `<`) contra os interpretadores detectados — o mais novo que
+  satisfaz a faixa vence, e falta de interpretador compatível é erro
+  honesto antes de qualquer mutação.
+- **Cache offline**: `--offline` resolve apenas pelo cache local
+  (`~/.forge-cli/cache/pypi/`, TTL 1h); falha de rede cai no cache
+  automaticamente quando existe.
+- **Receipts auditáveis**: `install.json` por Forja + `state.json`
+  consolidado registram dist, versão, `requires_python`, interpretador
+  escolhido, digests sha256 dos artefatos e o verify (comando + ok) —
+  incluindo installs que falharam no verify, para diagnóstico.
+
+#### Fixed
+
+- `install` sem nomes no modo registry agora recusa com orientação
+  explícita em vez de cair no fluxo interativo do git.
+
+### Hardening pós-release
+
+#### Fixed
+
+- **`update --check` sem upstream**: repositório sem remote configurado
+  (ou sem tracking no branch) reportava `não foi possível verificar
+(unknown)` — implicando falha transitória onde o estado honesto é
+  `no-upstream`. Novo literal em `SyncFailure`; `updateCheck` resolve
+  `@{u}` **antes** do fetch (cobre `branch.<name>.remote` apontando para
+  `.` ou URL sem remote nomeado) e só então classifica `no-upstream`;
+  o texto mostra `sem upstream configurado` e o JSON propaga
+  `failure: "no-upstream"`.
+
+#### Changed
+
+- **`planActionsFor` exportado** (`src/wizard.ts`): o construtor das
+  ações do plano revisado no wizard vira superfície testável, junto a
+  `renderOperationPlan` — o fluxo interativo (@clack/prompts) continua
+  fronteira de TUI não simulada.
+
+#### Tests
+
+- `tests/wizard.test.ts` (novo, 15 casos): renderização do plano
+  (hash truncado, expiração, passos, marcador de não-reversível,
+  truncamento de arquivos em 8) e `planActionsFor` (clone vs pull,
+  gating por passo, `.env` e `verify` sempre presentes).
+- `tests/hosts.test.ts` (+12 casos): adapter **cursor** completo
+  (detect absent→installed→configured→integrated, merge-json com
+  preview e sem copyable, manual quando integrado, JSON inválido
+  recusado sem clobber, dry-run), **copilot** (detect via `gh copilot`
+  - `.config/gh`, plan gated por `mcp-config.json` existente) e
+    **devin** (detect via `.config/devin`, apply/validate recusam com
+    `hostUnsupported`).
+- `tests/config.test.ts` (+6 casos): bloco `ai` do `loadConfig` —
+  chaves válidas, limites (512–262144 bytes, 1000–300000 ms,
+  0–86400000 ms TTL), tipos errados descartados, `ai` não-objeto
+  ignorado sem erro.
+- `tests/ai-cache.test.ts` (novo, 8 casos): chave canônica (ordem de
+  chaves irrelevante, tipos distintos não colidem), TTL (expirado,
+  timestamp futuro, `ttl<=0`), entrada corrompida/shape inválido →
+  miss, eviction bounded por idade com tiebreak por nome.
+- `tests/git-revs.test.ts` (+6 casos): `updateCheck` reporta
+  `no-upstream` com e sem remote configurado, tracking local
+  (`branch.<name>.remote=.`, `git remote` vazio) resolve `@{u}` e não é
+  `no-upstream`, fetch falho classificado sem throw, `remoteTags` em
+  remote `file://` real (ordem semver, `--limit`, remote inacessível →
+  `null`).
+- `tests/e2e-cli.test.ts` (+1 caso): `update --check` ponta a ponta
+  reporta `no-upstream`/`sem upstream configurado` sem pendência.
+- `tests/doctor2.test.ts` (+4 casos): helpers de contexto (`listDir`
+  ordenado/nulo, `readJson` ok/erro, `boundEntries` com flag de
+  truncamento, `mkCheck`/`errMsg`).
 
 ### Programa ecosystem-2026 (cyc8-05)
 

package/README.md

@@ -41,23 +41,19 @@ feedback visual em tempo real.
 
 ## Instalação
 
-Clone este repositório e instale as dependências:
+**Usuário final — via npm (recomendado):**
 
 ```bash
-git clone https://github.com/EdgarSocrates98/forge-cli.git
-cd forge-cli
-npm install
-```
-
-Para rodar sem compilar:
-
-```bash
-npm run dev
+npm i -g theforge-cli   # pacote publicado — sem clone necessário
+forge-cli               # TUI guiada
 ```
 
-Para compilar e usar como comando global:
+**Contribuidor — via clone:**
 
 ```bash
+git clone https://github.com/EdgarSocrates98/forge-cli.git
+cd forge-cli
+npm install
 npm run build
 npm link        # registra o binário `forge-cli`
 forge-cli       # em qualquer diretório
@@ -95,7 +91,33 @@ forge-cli install spark-forge-aws --profile recommended --scope project --compon
 
 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).
+silencioso. Veja [docs/capabilities.md](https://github.com/EdgarSocrates98/forge-cli/blob/v0.1.0/docs/capabilities.md).
+
+## Instalação via PyPI (registry-first — método recomendado)
+
+`forge-cli` sem argumentos abre a TUI guiada com **registry como opção
+recomendada** para as distribuições oficiais. O método git (clone +
+scripts) continua disponível para contribuidores — registry-first, não
+registry-only. `install --method registry`
+instala cada Forja direto do PyPI — sem clonar o repositório e sem
+exigir o The Forge. Cada Forja vai para uma venv isolada em
+`~/.forge-cli/forges/<nome>/` com `pip install <dist>==<versão>`
+pinado na estável mais nova (ou `--version`/`--ref` para pinar, uma
+Forja por comando). O interpretador escolhido é o mais novo que
+satisfaz `requires_python` do release; sem compatível, o install é
+recusado antes de qualquer mutação.
+
+- `forge-cli registry` lista o catálogo (7 dists) e o instalado.
+- Receipts em `install.json`/`state.json`: dist, versão, interpretador,
+  digests sha256 e verify — o artefato da dist é conferido byte a byte
+  após o download.
+- `--offline` resolve do cache local (metadados em
+  `~/.forge-cli/cache/pypi/`, wheels em `cache/wheels/<dist>/`);
+  artefato ausente = recusa honesta, nunca instalação fingida.
+- Releases yanked (PEP 592) são puladas na escolha automática; só
+  instalam por pin explícito e ficam marcadas no receipt.
+- `uninstall --method registry` remove venv + receipt com plano e
+  confirmação (`--yes`); `--all`/`--only` resolvem o conjunto instalado.
 
 ## Independência
 
@@ -111,6 +133,10 @@ forge-cli status                             # estado local (clonado, versão, a
 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 install api-forge --method registry # instala do PyPI em venv isolada (~/.forge-cli/forges/)
+forge-cli install --all --method registry     # todas as Forjas publicadas via PyPI
+forge-cli registry                            # catálogo PyPI + instaladas (--json estrutura)
+forge-cli uninstall api-forge --method registry --yes  # remove venv + receipt registry
 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
@@ -235,12 +261,12 @@ 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)
+- [Arquitetura e decisões de design](https://github.com/EdgarSocrates98/forge-cli/blob/v0.1.0/docs/arquitetura.md)
+- [Matriz de capacidades das Forjas](https://github.com/EdgarSocrates98/forge-cli/blob/v0.1.0/docs/capabilities.md)
+- [Solução de problemas](https://github.com/EdgarSocrates98/forge-cli/blob/v0.1.0/docs/solucao-de-problemas.md)
+- [Como contribuir](https://github.com/EdgarSocrates98/forge-cli/blob/v0.1.0/CONTRIBUTING.md)
+- [Registro de mudanças](https://github.com/EdgarSocrates98/forge-cli/blob/v0.1.0/CHANGELOG.md)
 
 ## Licença
 
-[MIT](LICENSE) © 2026 Edgar Sócrates Caria
+[MIT](https://github.com/EdgarSocrates98/forge-cli/blob/v0.1.0/LICENSE) © 2026 Edgar Sócrates Caria