iron-edge 1.2.0 → 2.0.1

package/skills/clone-site/reference/workflow.md

@@ -0,0 +1,211 @@
+# Workflow completo de clonagem 1:1 — método consolidado
+
+> Extração integral do workflow manual do Kimi (Fases 0→5, 11 problemas, scripts,
+> QA, dicas, ferramentas) **reconciliada** com o que a skill `clone-site` automatiza.
+> Nada do método manual foi perdido: o que a skill não automatiza está marcado como
+> _gap / add-on opcional_ no fim. Use junto com [lessons.md](lessons.md) (diagnóstico).
+
+## TL;DR — o pipeline da skill mapeado nas Fases
+
+| Fase do método manual | Onde a skill faz |
+|---|---|
+| 0 Reconhecimento | `clone.sh` detecta tipo (spa-ssg/estático) + fontes-CDN via `curl` |
+| 1 Clonagem | `capture.mjs` (navegador, padrão) **ou** `wget_fallback.sh` |
+| 2 Correções pós-clone | embutidas no `capture.mjs` (reescrita) / `fix_paths.py` (modo wget) |
+| 3 Servidor local | `serve.py` |
+| 4 Verificação/QA | `verify.mjs` (screenshots original×clone + report.json) |
+
+Comando único: `bash scripts/clone.sh "<URL>" --out "<pasta>"`.
+
+---
+
+## Fase 0 — Reconhecimento
+
+**Objetivo:** entender a stack antes de clonar. A skill faz parte automaticamente; os
+comandos manuais abaixo ficam como referência para diagnóstico aprofundado.
+
+### 0.1 Identificar a stack
+```bash
+curl -sI https://site.com | grep -i "server\|x-powered-by"          # headers
+curl -s https://site.com | grep -o "__NEXT_DATA__\|__next_f\|buildId" | head   # Next.js
+curl -s https://site.com | grep -o "sc-[a-f0-9]*-[0-9]*" | head     # styled-components
+curl -s https://site.com | grep -o "tailwind\|bootstrap\|bulma" | head         # CSS fw
+curl -s https://site.com/sitemap.xml | grep -c "<loc>"              # nº de páginas
+```
+- **Skill:** `clone.sh` detecta `spa-ssg` vs `static` (regex `__NEXT_DATA__|_next|__NUXT__|data-reactroot|__remixContext|__next_f`) e `fontes-cdn` (typekit/googleapis/gstatic). _Gap leve:_ não inspeciona `buildId`/`sc-`/framework CSS nem conta sitemap (o crawl supre a contagem).
+
+### 0.2 Mapear URLs
+```bash
+curl -s https://site.com | grep -oE 'href="/[^"]*"' | sed 's/href="//;s/"$//' | sort -u
+```
+- **Skill:** `capture.mjs` faz **BFS de `<a href>` da mesma origin** (melhor que grep manual). _Gap:_ não lê `_buildManifest.js` para rotas dinâmicas **não-linkadas** → use `--include`/`--max-pages` ou liste as rotas órfãs manualmente.
+
+### 0.3 Recursos externos críticos
+Fontes (Google/Typekit/FontAwesome/custom) · CSS (styled inline/modules/Tailwind) ·
+JS (chunks Next, GSAP, jQuery) · imagens (lazy, `srcset`, `data-src`) · APIs/forms.
+- **Skill:** interceptação de **100% da rede** captura tudo isso automaticamente.
+
+### 0.4 Checklist de reconhecimento (apresente ao usuário antes de clonar)
+- [ ] SSG ou SSR/CSR? · [ ] framework? · [ ] autenticação? · [ ] nº de páginas? ·
+  [ ] formulários? · [ ] animações (GSAP/Lottie/Three)? · [ ] vídeos?
+- **Skill:** `clone.sh` imprime `tipo` + `fontes-cdn`; o resto vira limite documentado.
+  _Recomendado:_ formalizar um relatório de recon (ver Gaps).
+
+---
+
+## Fase 1 — Clonagem inicial
+
+### 1.1 Motor de navegador (PADRÃO da skill — supera wget/httrack)
+`capture.mjs`: Chromium navega ao vivo, intercepta cada resposta, salva o asset,
+reescreve refs para **root-absolutas**, localiza fontes de CDN, faz gap-fill.
+Captura SPAs client-rendered, lazy assets e animações que wget não pega.
+
+### 1.2 wget (fallback rápido p/ estático/SSG) — `wget_fallback.sh`
+```bash
+wget --mirror --convert-links --adjust-extension --page-requisites --no-parent \
+     --domains="host,bare,www.bare" --reject-regex "(logout|api/|admin|gtm\.js|gtag)" \
+     -e robots=off --user-agent="Mozilla/5.0 …" -P ./clone https://site.com/
+```
+Flags: `--mirror`(=`-r -N -l inf`) · `--convert-links`(offline) · `--adjust-extension`(.html) ·
+`--page-requisites`(css/js/img) · `--no-parent` · `--reject-regex` · `-P`(saída).
+**Limite:** wget NÃO baixa fontes de CDN travadas por domínio (Typekit) → CSS quebra em
+localhost. Por isso o navegador é o padrão.
+
+### 1.3 httrack (alternativa do doc — **não usada pela skill**)
+Substituído pelo Playwright. Mantido só como referência: `httrack "url" -O dir -F "Mozilla/5.0" -* +*.css +*.js +*.png +*.woff2 …`.
+
+### 1.4 Pós-clone: organização
+- **wget:** `wget_fallback.sh` achata `clone/<host>/* → clone/` e remove `.tmp/.orig`.
+- **navegador:** já nasce com host primário na raiz (sem achatar).
+
+---
+
+## Fase 2 — Correções pós-clone (os 7 problemas do doc)
+
+No **motor de navegador** quase tudo é resolvido na origem (captura correta + reescrita).
+No **modo wget** o `fix_paths.py` aplica os consertos. De-para por problema:
+
+| # | Problema | Causa | Solução na skill |
+|---|---|---|---|
+| 1 | Caminhos relativos quebrados (`../` `./`) | `<base href>` vazio / rota muda | `fix_paths.py:to_abs` (wget) + reescrita root-absoluta nativa (navegador) — trata `href/src/srcset/data-src/url()`, preserva `https/mailto/tel` |
+| 2 | CSS Typekit corrompido (`<style data-href>`) | wget quebra `url()` interna | `fix_paths.py` troca por `<link>` (wget); navegador **localiza a fonte de verdade** |
+| 3 | Chunks JS faltantes | wget não segue todos | `fix_paths.py` lê `_buildManifest.js` e cria stubs (wget); navegador captura o chunk real ao visitar a rota |
+| 4 | `url('')` / `url(/'')` vazio | wget + correção conflitam | navegador captura o CSS íntegro (evita na origem). _Gap:_ sem rotina de reparo p/ clones wget já danificados |
+| 5 | Imagens dinâmicas via JS | Next injeta em runtime | **gap-fill** + auto-scroll (busca refs não-capturadas via HTTP) — supera o scan manual de chunks |
+| 6 | Formulários sem backend | clone estático | **Resolvido (opt-in `--form-toast`):** injeta toast amigável (não `alert`) em forms sem action externa — ambos os motores |
+| 7 | Typekit sem classe `.tk-degular` no `<html>` | kit espera a classe | **Resolvido (padrão):** runtime injetado lê classes `.tk-*` do CSS e as aplica ao `<html>` — ambos os motores |
+
+---
+
+## Fase 3 — Servidor local (`serve.py`)
+
+Por que não o `http.server` padrão: não resolve rotas sem barra, MIME de fontes errado,
+sem CORS. O `serve.py` resolve:
+- `/rota` → `/rota/index.html`; `/rota.html` quando existe; fallback `--spa` → `/index.html`.
+- MIME correto: `.js .mjs .css .woff2 .woff .ttf .otf .webp .avif .svg .json .wasm`.
+- CORS + `no-cache` (dev); ignora `BrokenPipe/ConnectionReset`; `allow_reuse_address=True`;
+  `ThreadingMixIn`; anti path-traversal (valida dentro de ROOT).
+- Ignora query cache-bust (`?dpl=`/`?v=`) e casa `foo.<hash>.ext` por prefixo.
+- _Diferença vs doc:_ porta default **8765** (doc usa 8888); **sem** redirect 301
+  trailing-slash (mitigado porque as refs são root-absolutas).
+
+Background: `clone.sh` sobe em background e informa o PID. (Doc usa `screen -dmS`; equivalente.)
+Porta em uso → `--port N` ou `lsof -ti:PORTA | xargs kill -9`.
+
+---
+
+## Fase 4 — Verificação e QA (`verify.mjs`)
+
+- **404s + console + fontes por rota:** navega original e clone, coleta
+  `cloneFailedRequests`, `cloneConsoleErrors`, e cruza `document.fonts` →
+  `fontsMissingInClone`. (Doc fazia scan estático de `src/srcSet/url()`; a skill testa
+  pelos requests reais — mais fiel, mas só o que a página dispara.)
+- **Screenshots comparativos:** full-page de **original × clone** lado a lado em
+  `_verify/*.png` (doc só tirava do clone) + `report.json`.
+- **Checagens estáticas (resolvido):** `verify.mjs` conta `<style>`/`</style>` por HTML
+  (CSS truncado, #11) e lista chunks do `_buildManifest` OK/MISSING/stub — em
+  `report.json` → `staticChecks`.
+
+---
+
+## Checklist final (com como a skill cobre)
+
+| Item do checklist | Cobertura |
+|---|---|
+| Todas as páginas HTTP 200 | parcial — `verify.mjs` testa rotas alcançadas pelo crawl |
+| Sem 404 em img/CSS/JS/fontes | sim — `report.json` (`cloneFailedRequests`, `fontsMissingInClone`) |
+| CSS inline não truncado (`<style>`=`</style>`) | sim — `report.staticChecks.cssTruncated` |
+| Fontes carregam | sim — `fontsMissingInClone` programático |
+| Animações funcionam | parcial — JS capturado; validação visual (screenshots) |
+| Formulários mostram msg amigável | sim (opt-in) — `--form-toast` |
+| Links internos funcionam | parcial — routing resolve; sem teste por link |
+| Links externos (WhatsApp/Typekit/GTM) | parcial — preservados; **trackers removidos por padrão** (use `--keep-trackers`) |
+| Meta viewport em todas | **não** verificado (vem no HTML as-is) |
+| Servidor roda sem erros | sim |
+| HANDOFF.md | sim — `clone.sh` gera `HANDOFF.md` + `_clone-manifest.json` + `report.json` |
+
+---
+
+## Dicas avançadas (status na skill)
+
+1. **Imagens grandes** (imagemin/WebP/lazy) — fora de escopo (clone fiel, sem otimizar).
+2. **Autenticação** — **resolvido:** `--storage-state <file>` carrega cookies/sessão
+   logada (gere com `npx playwright codegen --save-storage=state.json <url>`).
+3. **Infinite scroll** — coberto: `autoScroll` dispara lazy/infinite content.
+4. **Manter atualizado** (cron/rsync) — fora de escopo (sem sync incremental).
+5. **Performance** (Lighthouse/minify/cache headers) — fora de escopo; `serve.py` é
+   no-cache por design (dev).
+
+---
+
+## Ferramentas
+
+| Ferramenta | Uso na skill |
+|---|---|
+| Playwright/Chromium | **motor principal** (`capture.mjs`, `verify.mjs`) |
+| wget | fallback (`wget_fallback.sh`) |
+| curl | detecção (`clone.sh`), gap-fill, download seletivo |
+| python3 | `serve.py`, `fix_paths.py` |
+| cheerio | parse/reescrita de HTML em `capture.mjs` |
+| httrack · imagemin · rsync | **não usadas** (substituídas/fora de escopo) |
+
+---
+
+## O que a skill faz ALÉM do método manual
+
+1. **Motor de navegador** com interceptação de 100% da rede → SPAs, lazy, animações.
+2. **Localização real de fontes Typekit/Google travadas por domínio** (captura os
+   binários `/af/…` no domínio original e reescreve `@font-face`) — resolve o "CSS
+   quebrado" que no doc fica como limitação irresolvível no wget.
+3. **Gap-fill** automático de assets referenciados-mas-não-capturados.
+4. **Salvamento pré-hidratação** (SSR/SSG) → React/Vue hidrata limpo, sem #418/#423.
+5. **Fix do React #423 / Flight RSC**: preserva `<script>self.__next_f.push(…)</script>`
+   do filtro de trackers (continha `gtag`/`clarity` no conteúdo e era removido por engano).
+6. **Query cache-bust** (`?dpl=`/`?v=`) tratada no `serve.py` (fallback `stem.*.ext`).
+7. **Anti-ENAMETOOLONG** (trunca segmentos >180 bytes; try/catch por asset).
+8. **Verificação comparativa original×clone** com screenshots de ambos + `report.json`.
+9. **Modo `--mobile`** (viewport 390×844 p/ assets responsivos).
+10. **Reescrita root-absoluta universal** → roda em qualquer rota e no Vercel sem config.
+11. **Bootstrap automático** do Playwright + seleção de motor com fallback (zero setup).
+
+---
+
+## Gaps fechados nesta versão
+
+Os gaps do método manual foram resolvidos:
+- **#6 formulários** → `--form-toast` (toast amigável, opt-in, ambos os motores).
+- **#7 classe `.tk-degular`** → runtime injetado ativa classes `.tk-*` no `<html>` (padrão).
+- **#11 CSS truncado + cobertura de chunks** → `verify.mjs` → `report.staticChecks`.
+- **Clonagem autenticada** → `--storage-state <file>` (cookies/sessão Playwright).
+- **HANDOFF.md** → gerado pelo `clone.sh` ao final.
+
+## Add-ons ainda fora de escopo (decisão consciente)
+
+- **Redirect 301 trailing-slash** no `serve.py` — desnecessário: as refs são
+  root-absolutas (mitigado), e o 301 adicionaria um round-trip/risco de loop.
+- **Reparo de `url('')` vazio** em clones wget **já corrompidos** — o motor de navegador
+  evita o problema na origem; reparar clones antigos danificados não compensa.
+- **Enumerar rotas dinâmicas** via `_buildManifest.js` (além do BFS de `<a href>`) —
+  formato varia por build; use `--include`/`--max-pages` para rotas órfãs.
+- **Modos pós-clone** (WebP/imagemin/Lighthouse/rsync) — otimização/sync, fora da
+  fidelidade 1:1.