feat(reconcile): per-file snapshot diff of upstream drift since the migration cut

[aka-sacci-ccr]

Problema

Migração Deno/Fresh → TanStack leva semanas. Durante a janela, o repo de origem continua recebendo commits que nunca chegam no repo migrado — e não existia nada que detectasse isso. migrate.ts é in-place, one-shot, e não grava proveniência (nenhum SHA de origem, nenhum mapeamento source→target persistido).

O que entra

deco-reconcile (packages/blocks-cli/scripts/reconcile.ts), bin novo:

npx -p @decocms/blocks-cli deco-reconcile \
  --source <clone Fresh> --base <SHA do corte> \
  --target <clone TanStack> --target-base <SHA do commit de migração>

Diffa BASE_SHA..SOURCE_HEAD na origem e emite um patch por arquivo — segmentar é o ponto, deixa a LLM processar um de cada vez em vez de engolir um patch inteiro. Por arquivo anexa:

• targetCandidates — basename match sobre o git ls-files do alvo, ranqueado pelo palpite convencional (src/<rel>, islands/→src/components/, static/→public/). Candidato para o agente confirmar, não veredito.
• collision — git log <target-base>..HEAD -- <candidato> no alvo, com os subjects. Não-vazio = alguém corrigiu à mão ali; reconciliar hunk a hunk em vez de aplicar a mudança upstream inteira.

Saída em <target>/.reconcile/<sourceHead:7>/: manifest.json (que também é o estado de retomada, campo done por arquivo), INDEX.md humano, patches/NNN-<slug>.patch. Zero escrita no alvo, zero julgamento.

Ruído filtrado: .deco/ (conteúdo de CMS sincroniza por canal próprio), .github/, lockfiles, binários.

.agents/skills/deco-reconcile-snapshot/SKILL.md — o protocolo de aplicação: é rebase, não re-migração. Aprender as regras de tradução do par corte↔migração em vez de lista decorada; resolver colisão perguntando se a correção local existe por causa da stack nova ou de um defeito que o upstream já resolveu; varrer o CSS aplicado atrás do dano de token de seletor que um codemod já causou antes; paridade como critério de aceite (bug upstream é portado como está); parar e reportar quando as colisões passarem do que cabe numa sentada de revisão humana.

O aplicador é o loop da skill — não há --apply. Escrever no alvo é julgamento.

Decisões

• bin, não exports — política declarada no "//exports" do package.json.
• Não reusa decideAction (migrate/phase-analyze.ts:212), que sabe o mapeamento real: é module-private e exige um FileRecord completo (classificação de island, detecção de re-export → leitura e parse de conteúdo). Basename match + convenção já entregam a shortlist e o agente confirma. Se o palpite errar na prática, exportar decideAction é o upgrade natural.

Verificação

packages/blocks-cli/scripts/reconcile.test.ts — 5 testes, verde. O e2e monta dois repos git temporários (origem com 2 commits, alvo com commit de migração + uma hand-fix depois) e confere que o lockfile é filtrado, que o patch carrega o hunk certo, e que a hand-fix pós-migração aparece como colisão.

Os 6 erros de typecheck no pacote são pré-existentes (confirmado com stash: 6 antes, 6 depois) e ficam todos em migrate/*.

🤖 Generated with Claude Code

---

Summary by cubic

Generates a per-file snapshot diff of upstream changes since the migration cut so migrated TanStack repos can safely rebase Fresh/Deno drift. Previously there was no drift detection; now the deco-reconcile CLI emits one patch per changed file, suggests target candidates, dedupes collision commits, and writes nothing to the target.

• Adds deco-reconcile bin in @decocms/blocks-cli. Usage: --source <fresh> --target <tanstack> --snapshot <cut-sha> with optional --target-snapshot; output at <target>/.reconcile/<sourceHead:7>/ (manifest.json with done, INDEX.md, patches/*).
• CLI change: replace --base with --snapshot; replace --target-base with optional --target-snapshot (auto-detected via the oldest add of MIGRATION_REPORT.md, else HEAD; the chosen commit is printed).
• Filters .deco/, .github/, _fresh/, lockfiles, binaries, submodule gitlinks, and now any path the migration deletes (single source of truth in scripts/migrate/delete-sets.ts used by both analyze and reconcile).
• Computes targetCandidates via basename match plus conventional path guesses; collision commits are deduped by SHA across candidates to avoid inflated counts.
• Adds .agents/skills/deco-reconcile-snapshot/SKILL.md (apply protocol: rebase, not re-migration) and reconcile.test.ts covering patch emission, filtering (including delete-sets), collision dedupe, and target snapshot auto-detection.
• No changes to existing generators or exports; functionality is opt-in via the bin.

^{Written for commit c541bf9. Summary will update on new commits.}

[github-actions]

🎉 This PR is included in version 7.45.0 🎉

The release is available on:

• blocks-v7.45.0
• GitHub release

Your semantic-release bot 📦🚀