Requisição 200 — Recuperação de arquivos do ambiente em execução (descida pelo motor de choques)

Origem: Humano, 2026-09-30: "criar uma nova requisição para recuperação de arquivos", no mesmo lugar da recuperação de dados de recursos…

Origem: Humano, 2026-09-30: "criar uma nova requisição para recuperação de arquivos", no mesmo lugar da recuperação de dados de recursos (gestor/controladores/agents/arquitetura/recuperacao-dados-recursos.php), com "a mesma operação do diff e da escolha: sobrescrever, manter ou mesclar", para subir e descer, projeto e core. Lotes Vinculados: BATCH-208. Status: implementada (BATCH-208 complete, 2026-09-30): feita pelo agente executor, revisada, mesclada e homologada no tenant pelo agente da req-198/199; homologação humana pendente. Repositório: [REDACTED] (core, público). Trabalhar numa worktree própria a partir do origin/main (ver Execução).

Contexto

Hoje a recuperação cobre só os dados: _api/project/recover devolve os *Data.json (e contents/); recuperacao-dados-recursos.php decompõe de volta em arquivos de recurso; c2f project:recover junta as pontas.
Não há caminho para trazer de volta os arquivos de código que mudaram no servidor (edição direta, hotfix).
A req-198 deixou no servidor o manifesto por camada (installation/manifests/<camada>.json: caminho → sha256 do que cada camada entregou; precedência projeto > plugin:<id> > core), o snapshot e o registro de choques.
A req-199 (BATCH-205, no main) entregou o motor de choques: instalacao_choque_acoes(), instalacao_choque_versoes(), instalacao_choque_resolver() e as regras em installation/regras.json, na biblioteca pura gestor/bibliotecas/instalacao-manifesto.php; o registro no banco em gestor/bibliotecas/atualizacoes-choques.php; a API /_api/project/conflicts e /resolve; o CLI c2f update:conflicts / update:resolve (com --json) e o cliente cli/src/Support/ProjectApiClient.php.

Diretriz do Humano (2026-09-30)

A recuperação usa a mesma operação de diff e decisão do deploy: para cada arquivo diferente, ver o diff e escolher sobrescrever, manter ou mesclar ("esse sim, esse não"). Vale no nível de projeto e no nível do core. O motor é o da req-199, comum a subir e descer; não criar um fluxo de decisão paralelo.

Itens

Inventário no servidor — endpoint POST /_api/project/files (nome livre, documentar):
- compara o disco com os manifestos de cada camada e devolve, por arquivo: camada, caminho, estado (editado: hash do disco ≠ manifesto; ausente: no manifesto e fora do disco; fora-do-manifesto: arquivo no disco que nenhuma camada entregou, fora das pastas protegidas de INSTALACAO_PASTAS_FORA), hash_disco, hash_manifesto;
- filtros: camadas (padrão todas), caminhos (prefixos), estados;
- com baixar: true e uma lista de caminhos, devolve um ZIP com esses arquivos (como o recover faz com os dados); nunca sai nada de autenticacoes/, .env, logs/, backups/, temp/.
- Autenticado (api_authenticate), leitura pura (sem trava de deploy).
Descida no CLI — c2f project:recover-files <projeto> (nome livre, documentar), com --simular (padrão), --aplicar, --camada=projeto|core|plugin:<id>, --json:
- baixa o inventário e os arquivos diferentes para temp/recover-files/<projeto>/<execução>/;
- para a camada projeto, compara com o repositório local do projeto (gestorPath do ProjectEnvironmentResolver):
  - local igual ao que o projeto entregou (hash do manifesto) → a versão do servidor pode ser aplicada direto (com --aplicar);
  - local também mudou → choque de descida, decidido com o mesmo motor (sobrescrever o local com a do servidor, manter o local, mesclar), reaproveitando instalacao_choque_acoes/resolver e as regras (se for preciso um parâmetro novo no motor — por exemplo, a cópia fora da base —, acrescentar sem quebrar os chamadores atuais e cobrir com teste);
- para a camada core (e plugins): só baixa para análise e lista (o core não é aplicado num repositório de projeto); a decisão sobre esse arquivo no servidor já existe pelo update:resolve.
- --json para a extensão do VS Code (mesmo padrão de update:conflicts --json).
Registro: as descidas decididas ficam anotadas (arquivo JSON por execução em temp/recover-files/.../relatorio.json basta; não criar tabela nova no servidor para a descida).
Docs (pt-br e en, contrato de frontmatter; docs:audit sem aviso nos arquivos tocados): referência da API de projeto, CLI (família do comando) e o conceito de atualizações.

Critérios de aceite

Um arquivo do projeto editado direto no servidor aparece no inventário como editado; com --aplicar, desce para o repositório local quando o local está intacto; quando o local também mudou, vira choque de descida e as três decisões funcionam.
Um arquivo do core editado no servidor aparece no inventário e é baixado para análise, sem tocar o repositório local.
Nada sensível sai pelo ZIP (teste automatizado cobrindo .env, autenticacoes/, logs/, backups/, temp/, ..).
PHPUnit verde nos testes novos e nos do lote da req-198/199 (--filter 'UpdateConflicts|UpdateRollback|AtualizacoesManifesto|InstalacaoManifesto|AtualizacoesSistemaTrava|DeployLock|MigrationChecker'); homologação no tenant isolado.

Execução (para o agente executor)

Worktree própria: git -C [REDACTED] fetch origin e git -C ... worktree add ..\conn2flow-req200 -b feat/req-200 origin/main. Não use o diretório principal do core (tem trabalho não commitado de outro agente) nem a worktree conn2flow-bl028.
PHPUnit na worktree: php ../conn2flow/vendor/bin/phpunit --configuration phpunit.xml; copie dev-environment/data/environment.json do diretório principal para a worktree (é ignorado pelo git). Falhas de ambiente conhecidas na worktree: CoreHelpersTest (RSA), Stripe*Test, CssRegeneracaoTest (CRLF).
Ambiente de teste: o projeto [REDACTED] do environment.json (local: true) → tenant isolado [REDACTED] no [REDACTED] (usuário HestiaCP c2ftest; nginx em [REDACTED]:8443/, api_resolve_ip: [REDACTED]; token de API já em devProjects.[REDACTED].api.access_token). O tenant tem manifestos das camadas core e projeto (installation/manifests/). Ele é compartilhado com o agente da req-201: não rode atualização do sistema nem deploy nele (a req-200 só lê e baixa); para criar edições de teste, use ssh [REDACTED] "sudo -u c2ftest ..." em arquivos da pasta bibliotecas/fpdf184/ ou bibliotecas/SimpleImage/.
Regras do projeto: SDD do core (sdd/README.md, process/, BATCH-INDEX.md, VALIDATION-CHECKLIST.md, DECISION-LOG.md, memórias); abrir sdd/implementation/BATCH-208.md; git add só com caminhos explícitos (nunca -A/-a); nunca deploy em produção; não mexer em sdd/MEMORIA-ENGENHARIA-CHEFIA.md; heredoc do bash corrompe barras (use Write/Edit ou scripts Python). O core é público: nada de dados privados da operação.
Entrega: commit(s) e push na branch feat/req-200 (não no main). Avise o Humano; o agente da req-198/199 revisa e mescla.
Não tocar: gestor/controladores/atualizacoes/atualizacoes-sistema.php e o fluxo de atualização do sistema em api.php (api_system_*) — são da req-201, em andamento em paralelo. Funções novas em api.php podem entrar no bloco do api_handle_project().

# Requisição 200 — Recuperação de arquivos do ambiente em execução (descida pelo motor de choques)
**Origem**: Humano, 2026-09-30: "criar uma nova requisição para recuperação de arquivos", no mesmo lugar da recuperação de dados de recursos (`gestor/controladores/agents/arquitetura/recuperacao-dados-recursos.php`), com "a mesma operação do diff e da escolha: sobrescrever, manter ou mesclar", para subir e descer, projeto e core.
**Lotes Vinculados**: `BATCH-208`.
**Status**: implementada (BATCH-208 `complete`, 2026-09-30): feita pelo agente executor, revisada, mesclada e homologada no tenant pelo agente da req-198/199; homologação humana pendente.
**Repositório**: `[REDACTED]` (core, **público**). Trabalhar numa worktree própria a partir do `origin/main` (ver Execução).
---
## Contexto
- Hoje a recuperação cobre só os **dados**: `_api/project/recover` devolve os `*Data.json` (e `contents/`); `recuperacao-dados-recursos.php` decompõe de volta em arquivos de recurso; `c2f project:recover` junta as pontas.
- Não há caminho para trazer de volta os **arquivos de código** que mudaram no servidor (edição direta, hotfix).
- A req-198 deixou no servidor o **manifesto por camada** (`installation/manifests/<camada>.json`: caminho → sha256 do que cada camada entregou; precedência `projeto` > `plugin:<id>` > `core`), o snapshot e o registro de choques.
- A req-199 (BATCH-205, no `main`) entregou o **motor de choques**: `instalacao_choque_acoes()`, `instalacao_choque_versoes()`, `instalacao_choque_resolver()` e as regras em `installation/regras.json`, na biblioteca pura `gestor/bibliotecas/instalacao-manifesto.php`; o registro no banco em `gestor/bibliotecas/atualizacoes-choques.php`; a API `/_api/project/conflicts` e `/resolve`; o CLI `c2f update:conflicts` / `update:resolve` (com `--json`) e o cliente `cli/src/Support/ProjectApiClient.php`.
## Diretriz do Humano (2026-09-30)
A recuperação usa **a mesma operação de diff e decisão** do deploy: para cada arquivo diferente, ver o diff e escolher sobrescrever, manter ou mesclar ("esse sim, esse não"). Vale no nível de projeto e no nível do core. O motor é o da [req-199](req-199.md), comum a subir e descer; **não criar um fluxo de decisão paralelo**.
## Itens
1. **Inventário no servidor** — endpoint `POST /_api/project/files` (nome livre, documentar):
   - compara o disco com os manifestos de cada camada e devolve, por arquivo: `camada`, `caminho`, `estado` (`editado`: hash do disco ≠ manifesto; `ausente`: no manifesto e fora do disco; `fora-do-manifesto`: arquivo no disco que nenhuma camada entregou, fora das pastas protegidas de `INSTALACAO_PASTAS_FORA`), `hash_disco`, `hash_manifesto`;
   - filtros: `camadas` (padrão todas), `caminhos` (prefixos), `estados`;
   - com `baixar: true` e uma lista de caminhos, devolve um ZIP com esses arquivos (como o `recover` faz com os dados); nunca sai nada de `autenticacoes/`, `.env`, `logs/`, `backups/`, `temp/`.
   - Autenticado (`api_authenticate`), leitura pura (sem trava de deploy).
2. **Descida no CLI** — `c2f project:recover-files <projeto>` (nome livre, documentar), com `--simular` (padrão), `--aplicar`, `--camada=projeto|core|plugin:<id>`, `--json`:
   - baixa o inventário e os arquivos diferentes para `temp/recover-files/<projeto>/<execução>/`;
   - para a camada **projeto**, compara com o repositório local do projeto (`gestorPath` do `ProjectEnvironmentResolver`):
     - local igual ao que o projeto entregou (hash do manifesto) → a versão do servidor pode ser aplicada direto (com `--aplicar`);
     - local também mudou → **choque de descida**, decidido com o mesmo motor (sobrescrever o local com a do servidor, manter o local, mesclar), reaproveitando `instalacao_choque_acoes/resolver` e as regras (se for preciso um parâmetro novo no motor — por exemplo, a cópia fora da base —, acrescentar sem quebrar os chamadores atuais e cobrir com teste);
   - para a camada **core** (e plugins): só baixa para análise e lista (o core não é aplicado num repositório de projeto); a decisão sobre esse arquivo no servidor já existe pelo `update:resolve`.
   - `--json` para a extensão do VS Code (mesmo padrão de `update:conflicts --json`).
3. **Registro:** as descidas decididas ficam anotadas (arquivo JSON por execução em `temp/recover-files/.../relatorio.json` basta; não criar tabela nova no servidor para a descida).
4. **Docs** (pt-br e en, contrato de frontmatter; `docs:audit` sem aviso nos arquivos tocados): referência da API de projeto, CLI (família do comando) e o conceito de atualizações.
## Critérios de aceite
1. Um arquivo do **projeto** editado direto no servidor aparece no inventário como `editado`; com `--aplicar`, desce para o repositório local quando o local está intacto; quando o local também mudou, vira choque de descida e as três decisões funcionam.
2. Um arquivo do **core** editado no servidor aparece no inventário e é baixado para análise, sem tocar o repositório local.
3. Nada sensível sai pelo ZIP (teste automatizado cobrindo `.env`, `autenticacoes/`, `logs/`, `backups/`, `temp/`, `..`).
4. PHPUnit verde nos testes novos e nos do lote da req-198/199 (`--filter 'UpdateConflicts|UpdateRollback|AtualizacoesManifesto|InstalacaoManifesto|AtualizacoesSistemaTrava|DeployLock|MigrationChecker'`); homologação no tenant isolado.
## Execução (para o agente executor)
- **Worktree própria:** `git -C [REDACTED] fetch origin` e `git -C ... worktree add ..\conn2flow-req200 -b feat/req-200 origin/main`. **Não** use o diretório principal do core (tem trabalho não commitado de outro agente) nem a worktree `conn2flow-bl028`.
- **PHPUnit na worktree:** `php ../conn2flow/vendor/bin/phpunit --configuration phpunit.xml`; copie `dev-environment/data/environment.json` do diretório principal para a worktree (é ignorado pelo git). Falhas de ambiente conhecidas na worktree: `CoreHelpersTest` (RSA), `Stripe*Test`, `CssRegeneracaoTest` (CRLF).
- **Ambiente de teste:** o projeto `[REDACTED]` do `environment.json` (`local: true`) → tenant isolado `[REDACTED]` no [REDACTED] (usuário HestiaCP `c2ftest`; nginx em `[REDACTED]:8443/`, `api_resolve_ip: [REDACTED]`; token de API já em `devProjects.[REDACTED].api.access_token`). O tenant tem manifestos das camadas `core` e `projeto` (`installation/manifests/`). Ele é compartilhado com o agente da req-201: **não rode atualização do sistema nem deploy nele** (a req-200 só lê e baixa); para criar edições de teste, use `ssh [REDACTED] "sudo -u c2ftest ..."` em arquivos da pasta `bibliotecas/fpdf184/` ou `bibliotecas/SimpleImage/`.
- **Regras do projeto:** SDD do core (`sdd/README.md`, `process/`, `BATCH-INDEX.md`, `VALIDATION-CHECKLIST.md`, `DECISION-LOG.md`, memórias); abrir `sdd/implementation/BATCH-208.md`; `git add` só com caminhos explícitos (nunca `-A`/`-a`); nunca deploy em produção; não mexer em `sdd/MEMORIA-ENGENHARIA-CHEFIA.md`; heredoc do bash corrompe barras (use Write/Edit ou scripts Python). O core é **público**: nada de dados privados da operação.
- **Entrega:** commit(s) e push na branch `feat/req-200` (não no `main`). Avise o Humano; o agente da req-198/199 revisa e mescla.
- **Não tocar:** `gestor/controladores/atualizacoes/atualizacoes-sistema.php` e o fluxo de atualização do sistema em `api.php` (`api_system_*`) — são da req-201, em andamento em paralelo. Funções novas em `api.php` podem entrar no bloco do `api_handle_project()`.