/recovery-crawl

description: "Screaming Frog crawl with technical SEO issue classification including Shopware-specific patterns."
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__*

Recovery Crawl

Zweck

Screaming Frog MCP Crawl durchfuehren und die Ergebnisse in eine strukturierte, priorisierte Issues-Liste transformieren. Identifiziert technische SEO-Probleme die Recovery blockieren. Falls Screaming Frog MCP nicht verfuegbar ist, Fallback auf CSV-Import; ohne CSV-Import bricht das Command mit Status `failed` ab.

Trigger

`/seo-rescue:recovery-crawl <domain>`

Input-Kontrakt

| Feld | Quelle | Pflicht | |------|--------|---------| | `domain` | CLI-Argument | ja |

Normalisierung gemaess Schritt 1 des Ablaufs. `www.` wird NICHT entfernt.

Capabilities

| Capability | Pflicht/Optional | Verwendung | |-----------|-----------------|-----------| | `crawl_issues` | pflicht (mit Fallback) | Technische SEO-Issues identifizieren | | `indexability_check` | optional | Canonicals, noindex, robots-Blockierung pruefen | | `page_metadata` | optional | H1, Meta-Description, Title extrahieren |

Bevorzugte Provider

• **crawl_issues**: Screaming Frog MCP (`sf_crawl`, `sf_generate_bulk_export`)
• **indexability_check**: Screaming Frog MCP (`Canonicals:Non-Indexable` Filter)
• **page_metadata**: Screaming Frog MCP (`H1:Missing`, `Meta Description:Missing`)

Fallback-Provider

Paid Fallbacks (wenn Screaming Frog MCP nicht verfuegbar)

| Capability | Paid Fallback | |-----------|--------------| | `crawl_issues` | Sitebulb, JetOctopus, Lumar (Deepcrawl), Botify (manueller CSV-Export) | | `indexability_check` | Sitebulb, Lumar | | `page_metadata` | Sitebulb, JetOctopus |

Free / Lokale Fallbacks

| Capability | Free/Lokal Fallback | |-----------|-------------------| | `crawl_issues` | Manuelle Crawl-CSV unter `~/.cache/seo-rescue/{slug}/imports/crawl.csv` | | `page_metadata` | Manuelle Crawl-CSV mit H1/Meta-Spalten |

CSV-Importe werden unter `~/.cache/seo-rescue/{slug}/imports/` erwartet.

Script CLI Contract

node scripts/recovery-crawl.js --domain <domain> --cache-dir <path>

| Exit Code | Bedeutung | |-----------|-----------| | `0` | Crawl abgeschlossen (complete oder partial) | | `1` | Crawl fehlgeschlagen (kein Provider, kein CSV) | | `2` | Security-Abbruch (Symlink, Path-Traversal) | | `3` | Lock-Timeout (anderer Command laeuft) |

Ablauf

Schritt 1: Domain normalisieren

Normalisiere den Input gemaess dem gemeinsamen Input-Kontrakt:

• Entferne Protokoll (`https://`, `http://`), Pfad, Query-Parameter, Fragment, Trailing Slash
• `www.` wird NICHT entfernt — `www.example.com` und `example.com` sind verschiedene Domains
• Erzeuge folgende Felder:
• `input_domain` — das Original exakt so wie vom User eingegeben
• `domain` — normalisierte Domain (kein Protokoll, kein Pfad, kein Trailing Slash)
• `canonical_domain` — auf `null` setzen (wird von spaeteren Commands gesetzt)
• `slug` — sicherer Dateiname via `safeSlug()` aus `lib/safe.js`

Fuehre aus:

node -e "const { normalizeDomain } = require('./plugins/seo-rescue/lib/safe.js'); console.log(JSON.stringify(normalizeDomain('{domain}')))"

Ersetze `{domain}` durch den tatsaechlichen User-Input. Falls `normalizeDomain()` einen Fehler wirft (z.B. leerer Input, ungueltiger Slug), Abbruch mit Status `failed`.

Schritt 2: Cache-Verzeichnis anlegen

Erstelle das domainspezifische Cache-Verzeichnis unter `~/.cache/seo-rescue/{slug}/`:

node -e "const { ensureDomainDir } = require('./plugins/seo-rescue/lib/safe.js'); console.log(ensureDomainDir('{slug}'))"

Ersetze `{slug}` durch den in Schritt 1 ermittelten Slug. Das Verzeichnis wird mit Modus 0700 angelegt (nur der aktuelle User hat Zugriff). Falls das Verzeichnis ein Symlink ist, Abbruch mit Status `failed`.

Schritt 3: Run-ID generieren

Falls eine `run_id` vom Orchestrator (`recovery-full`) uebergeben wurde: diese unveraendert verwenden, KEIN eigenes Prefix erzeugen. Sonst generiere eine eindeutige Run-ID fuer diesen Lauf:

node -e "const { randomUUID } = require('crypto'); console.log('crawl-' + randomUUID().slice(0,8) + '-' + Date.now())"

Speichere die Run-ID als `run_id`. Sie wird im Output-Schema mitgefuehrt.

Schritt 4: Crawl starten (Screaming Frog MCP)

Starte den Screaming Frog MCP Crawl mit dem Tool `sf_crawl`:

• URL: `https://{domain}` (normalisierte Domain mit Protokoll)
• Crawl-Limit: 500 URLs

Speichere die Crawl-ID aus der Antwort fuer die nachfolgende Fortschrittsueberwachung.

Falls `sf_crawl` nicht verfuegbar ist oder sofort einen Fehler zurueckgibt:

• Warnung in `warnings` eintragen: `"Screaming Frog MCP nicht verfuegbar — Fallback wird versucht"`
• Weiter mit Schritt 7 (Fallback-Strategie)

Schritt 5: Fortschritt ueberwachen (Screaming Frog MCP)

Nur wenn Schritt 4 erfolgreich war:

Rufe `sf_crawl_progress` mit der Crawl-ID in regelmaessigen Abstaenden auf, bis der Crawl abgeschlossen ist.

• Pruefe den Status auf `"complete"` oder `"finished"`
• Bei Status `"aborted"` oder `"error"`: Warnung eintragen `"Crawl wurde abgebrochen — partielle Daten"`, Status = `partial`, weiter mit Schritt 6 falls teilweise Daten vorhanden
• Bei Timeout (> 10 Minuten ohne Abschluss): Warnung eintragen `"Crawl-Timeout — moegliche partielle Daten"`, weiter mit Schritt 6

Schritt 6: Bulk-Exports generieren (Screaming Frog MCP)

Nur wenn SF-Crawl abgeschlossen oder partial:

Generiere fuer folgende Filter jeweils einen Export via `sf_generate_bulk_export` und lies das Ergebnis mit `sf_export_crawl`:

| Filter-Name | Export-Typ | Mapping auf Issue-Typ | |-------------|------------|----------------------| | `Response Codes:Client Error (4xx)` | Internal HTML | `broken_internal_link` | | `Response Codes:Redirection (3xx)` | Internal HTML | `redirect_chain` | | `H1:Missing` | Internal HTML | `missing_h1` | | `H1:Duplicate` | Internal HTML | `duplicate_h1` | | `Meta Description:Missing` | Internal HTML | `