teqo-backup/docs/plans/ops60-seed-posts-guard-escrita-s3-impl.md

156 lines
8.3 KiB
Markdown

# Impl: OPS60 — Guard de intenção explícita para escrita no bucket via `db:seed:posts`
Status: aprovado (gate humano 2026-08-18)
Atualizado em: 2026-08-18
Issue: #49 (OPS60)
Intenção: docs/plans/ops60-seed-posts-guard-escrita-s3.md
Appetite restante: herdado (~0,5 dia — um outcome verificável; sem migration/UI)
## Leitura da intenção
- **Outcome:** o modo sync (padrão) do `pnpm db:seed:posts` só escreve media no
bucket S3 das envs `S3_*` com **intenção explícita** — `SEED_MEDIA_CONFIRM=1`
(mesmo padrão `isTruthyEnv` da #37) — e recusa com mensagem clara sem ela;
`--dry-run` segue desprotegido (não escreve). O risco fechado: um worktree
que receba credenciais `S3_*` de prod (cópia all-or-nothing do
`worktree-env.mjs`) rodando o seed contra DB local sobrescreveria covers no
bucket de **prod** — a mesma classe de risco que a #37 fechou para
`media:recover`, ainda aberta no seed.
- **O que NÃO negociar:** fail-closed (sem flag → sem escrita no bucket, em
qualquer cenário de DB/alvo); comportamento local sem `S3_*` (→ disk) e o
upload via admin/CI de prod intactos; `--dry-run` sem fricção nova; guard no
dono (`isTruthyEnv` em `cli.mjs`) — sem twin.
- **O que reavaliar:** a alternativa do aceite "**ou recusa apontar para bucket
não-local**" — ver Opções (B).
## Abordagem recomendada
```mermaid
flowchart LR
A[pnpm db:seed:posts] -->|parse args --dry-run| B{mode == sync?}
B -->|não| C[segue — dry-run não escreve, sem guard]
B -->|sim| D{S3_* completo?<br/>resolveS3StorageEnv.enabled}
D -->|não| E[segue sem guard — storage local (disk)]
D -->|sim| F{SEED_MEDIA_CONFIRM true/1?}
F -->|não| G[die com o comando correto — antes de DB/rede]
F -->|sim| H[guards existentes + echo do alvo + sync]
```
**Opções consideradas (forma do guard):**
- **A — Env flag `SEED_MEDIA_CONFIRM` (truthy `true|1` via `isTruthyEnv`)
obrigatória no sync quando o storage S3 está ativo**
(`resolveS3StorageEnv(process.env).enabled`). **Recomendada.**
- B — Recusar bucket não-local: allowlist de endpoints/buckets "locais" e die
para qualquer outro alvo.
- C — Guard incondicional no sync (mesmo com storage local).
**Recomendação: A** — paridade total com o guard da #37 (`MEDIA_RECOVER_CONFIRM`)
e com o guard de DB (`ALLOW_REMOTE_DB`): funciona em runbook não-interativo
(SSH, `set -a; source teqo-1313.env`), a condição usa o dono já existente
(`resolveS3StorageEnv` — sem nova lógica de leitura de env), e a escrita que o
guard protege é exatamente a escrita no bucket (media via adapter S3), deixando
o fluxo dev local intocado.
**Rejeitadas:** B (o "local" do Garage é ambíguo por construção — o endpoint
varia por contexto: `host.docker.internal:3900` dentro do compose,
`100.119.220.31:3900` na workstation/tailnet, `127.0.0.1:3900` no host do
homeserver; uma allowlist de hosts teria que errar em algum lugar ou bloquear o
sync de prod legítimo — o guard da #37 já provou que a env flag é o padrão do
repo); C (quebraria o fluxo dev local: todo `db:seed:posts` exigiria a flag
mesmo sem bucket; o aceite pede explicitamente o comportamento local intacto).
### Componentes / mudanças
- **`scripts/seed-posts.mjs`** (extensão do dono — comportamento dev local
inalterado; paridade estrutural com `scripts/recover-media.mjs:79-85`):
- Constante `SEED_MEDIA_CONFIRM_FLAG = 'SEED_MEDIA_CONFIRM'`; import de
`isTruthyEnv` (de `./lib/cli.mjs`) e `resolveS3StorageEnv` (de
`../src/utilities/mediaStorage.ts`).
- Imediatamente após o parsing de args/modo e **antes** de
`assertLocalDatabase` / `getPayload` (fail fast — zero DB, zero rede):
```js
const storage = resolveS3StorageEnv(process.env) // throws em S3_* parcial (fail-closed, mesmo contrato do boot)
if (mode === 'sync' && storage.enabled && !isTruthyEnv(process.env[SEED_MEDIA_CONFIRM_FLAG])) {
die(
'o sync ESCREVE media no bucket S3 das envs S3_* — exige confirmação explícita de intenção.\n' +
` Re-rodar com: ${SEED_MEDIA_CONFIRM_FLAG}=1 pnpm db:seed:posts\n` +
' (ou use --dry-run para planejar sem escrever).',
)
}
```
- Echo do alvo ganha `Bucket`/`Endpoint` quando `storage.enabled` (paridade
com o `targetSummary` do `recover-media.mjs`).
- Bloco de comentário do header (safety model + usage) atualizado para
documentar o guard.
- O gate vale para sync com QUALQUER alvo de DB (local ou remoto) — o risco
é a escrita no bucket, não a origem dos dados (mesma decisão da #37).
- **`package.json`:** nada — a flag é env, não arg do script.
- **Migration:** nenhuma. **Access / Consent:** intocados. **UI:** N/A
(Impeccable A — conteúdo/operação).
- **Docs:** runbook do `docs/plans/ops58-sincronizar-posts-prod-impl.md`
(passo 3 do runbook ganha `SEED_MEDIA_CONFIRM=1` + nota OPS60; passo 2
pre-flight ganha nota de que o dry-run segue sem a flag — não escreve);
nota curta no AGENTS.md (§ "Seeding news content" — sync com
`S3_*` exige `SEED_MEDIA_CONFIRM=1`; `--dry-run` segue sem flag); entrada
`docs/changelog/2026-08-18-ops60.md` + `pnpm changelog:build`.
## Fases verificáveis
1. **Guard no script** — `seed-posts.mjs` (gate + echo + header doc).
Validação de comportamento contra o DB local do worktree:
- Sem `S3_*`: `pnpm db:seed:posts` e `pnpm db:seed:posts --dry-run` seguem
exatamente como hoje (sem flag exigida).
- Com `S3_*` fake (ex.: `S3_BUCKET=teqo-media-test
S3_ENDPOINT=http://127.0.0.1:9 S3_ACCESS_KEY_ID=x S3_SECRET_ACCESS_KEY=x`):
sync → exit 1 com a mensagem do guard, **antes** de qualquer escrita
(conferir via contagem de posts/tags antes/depois — zero delta);
`--dry-run` com as mesmas envs → segue plan-only sem exigir flag.
2. **Docs + changelog** — runbook OPS58 (passo 3 + nota), AGENTS.md,
`docs/changelog/2026-08-18-ops60.md`, `pnpm changelog:build` +
`pnpm changelog:check`.
3. **Gates finais** — `pnpm gate:fast`, `pnpm format:check`, `pnpm exec knip`,
`pnpm check:cycles`, `pnpm test` (unit+int), `pnpm build` local; PR → CI
verde → merge em `main` (deploy automático OPS53).
## Rabbit holes / Não escopo (engenharia)
- **Testar o sync com S3 ponta a ponta** — impossível por contrato (sem
`S3_*` de prod nesta máquina; e o guard bloqueia o caminho por design); a
prova do caminho liberado é o runbook do homeserver (padrão OPS52 fase 3).
- **Teste unitário do gate inline** — mesmo padrão do `recover-media.mjs`
(parse inline, sem teste dedicado; decisões OPS52-media-guard e OPS58); a
semântica do flag já é unit-testada em `cliEnvFlags.unit.spec.ts`.
- **Guard para `--dry-run`** — não: não escreve; o aceite pede explicitamente
preservar a semântica atual do dry-run.
- **Banir re-escritas `=== '1'`/`=== 'true'` de env-read** no
`codebaseConventions` — defer registrado na intenção (gatilho: 4º site ou
refactor dos 3 existentes); não reabrir.
## Riscos e mitigação
- **R1 — S3\_\* parcial no env local derruba o seed.** Já acontece hoje: o
`payload.config.ts` resolve `mediaStorage` no import e aborta em config
parcial (fail-closed de boot, OPS52); a chamada de `resolveS3StorageEnv` no
guard tem o mesmo contrato e ocorre depois desse import — comportamento
inalterado, agora com mensagem explícita do dono.
- **R2 — Runbook de prod desatualizado manda rodar o sync sem a flag e o
guard recusa (fricção na próxima execução).** Mitigação: runbook OPS58
editado no mesmo PR; mensagem do die exibe o comando correto.
- **R3 — A flag vaza para outros modos (dry-run).** Mitigação: condição
restrita a `mode === 'sync' && storage.enabled`; o dry-run é validado com
`S3_*` fake na fase 1.
## Aceite de engenharia
- [ ] Aceite de produto da intenção coberto: sync com `S3_*` recusa sem
`SEED_MEDIA_CONFIRM=1` (fail-closed); dry-run e storage local
desprotegidos; admin/CI de prod intocados
- [ ] Invariantes AGENTS/engineering-standards: identificadores em inglês;
guard reusado do dono (`isTruthyEnv`/`resolveS3StorageEnv`) sem twin;
zero migration/access/Consent
- [ ] Testes/validação de domínio: die do guard com `S3_*` fake (zero delta
de rows no DB local); dry-run com `S3_*` fake segue plan-only; gates da
checklist do AGENTS
- [ ] Docs: runbook OPS58 atualizado (comando real com a flag) + nota
AGENTS.md + changelog