seo-apply

tseo — seo-apply

Applique les findings de <project>/.tseo/findings.json selon leur tier. Tu modifies le code source du projet cible. Toutes les modifications passent par git (commit par finding ou par batch). Aucune modif hors sandbox.

Modes d'invocation

1. Mode scopé (par défaut depuis v0.1.0-beta) : appelé par seo-audit Phase 3 avec un sous-ensemble de findings filtré sur un thème (ex: tous les HM-* du thème head-meta.md). Les sous-phases A/B/C s'exécutent sur ce sous-ensemble uniquement, puis seo-audit passe au thème suivant.
2. Mode standalone : invoqué directement par l'utilisateur sur un findings.json existant. Toutes les findings sont appliquées d'un coup (sous-phases A/B/C sur le set complet). Utile pour rejouer un audit ou appliquer après pause.

Les contraintes (pré-requis, sandbox, mtime, format de commits) sont identiques dans les deux modes.

Sandbox autorisé (en absolu, jamais étendu)

<project_path>/resources/views/**/*.blade.php
<project_path>/public/robots.txt
<project_path>/public/sitemap.xml
<project_path>/public/site.webmanifest
<project_path>/public/og-default.png       (placeholder uniquement, pas de génération)
<project_path>/app/Http/Controllers/**/*.php
<project_path>/routes/*.php
<project_path>/config/*.php
<project_path>/.tseo/**/*                  (artefacts internes, pas de commit)

Jamais : .env, .env.*, vendor/, storage/, database/, node_modules/, bootstrap/cache/, *.sqlite.

Pré-requis avant de toucher au moindre fichier

1. Vérifier que <project_path> est un repo git : git -C <project_path> rev-parse --git-dir. Sinon → STOP, "Le projet doit être un repo git pour permettre le rollback granulaire."
2. Vérifier que le working tree est clean : git -C <project_path> status --porcelain doit être vide. Sinon → STOP, "Working tree git sale. Stash ou commit tes changements avant de lancer apply."
3. Charger <project>/.tseo/findings.json. S'il manque → STOP, "Lance /seo-audit d'abord."
4. Vérifier le mtime de chaque file dans findings[*].evidence[*].file : doit être ≤ findings.audit_at. Si un fichier a été modifié après l'audit → SKIP ce finding avec warning et liste-le en fin pour ré-audit.
5. Vérifier que toute évidence et toute target de fix tombe dans le sandbox. Si un finding a sandbox: ["foo/bar"] qui sort des chemins autorisés ci-dessus → SKIP avec error.

Configuration git pour les commits

Avant le premier commit :

• Vérifier git -C <project_path> config user.email et user.name. S'ils manquent, demander à l'utilisateur de les configurer (ne les configurer pas automatiquement).
• Tous les commits ont le préfixe tseo: pour identification facile.
• Co-author trailer : Co-Authored-By: tseo <[email protected]>.

---

Sous-phase A — Auto-safe (batch)

Pour tous les findings avec tier: "auto-safe" ET previously_applied: false :

1. Affiche le récap :

   <X> fixes auto-safe à appliquer en batch :
   - HM-001 : Charset déclaré dans resources/views/layouts/app.blade.php
   - HM-002 : Viewport déclaré dans resources/views/layouts/app.blade.php
   - HM-006 : Canonical self-ref dans resources/views/layouts/app.blade.php
   - IL-003 : rel="noopener" sur 4 occurrences
   - PF-003 : preconnect fonts (resources/views/layouts/app.blade.php)
   - IX-001 : Création public/robots.txt
   ...
   

2. Demande validation globale : "OK pour appliquer ces fixes en un commit ?" (Oui / Non / Voir les diffs un par un)

   • Oui → continue.
   • Voir les diffs → bascule en mode auto-risky pour ce batch (1 par 1).
   • Non → STOP la sous-phase A, passe à la suivante.

3. Applique chaque fix dans l'ordre :

   • Pour fix.type == "insert_after" : Edit, insert fix.content après fix.anchor.line dans fix.anchor.file.
   • Pour fix.type == "insert_before" : idem, avant.
   • Pour fix.type == "replace" : Edit, remplace fix.old_string par fix.new_string dans fix.anchor.file.
   • Pour fix.type == "create_file" : Write fix.path avec fix.content.
   • Pour fix.type == "append" : Read + Write avec append fix.content.

4. Vérification après chaque fix :

   • Si Edit échoue (anchor introuvable, mtime changé, etc.) : LOG l'erreur, n'applique pas, continue avec les suivants.
   • Si tout réussit : passe au suivant.

5. Commit unique :

   git add <files modifiés/créés>
   git commit -m "tseo: apply <X> auto-safe SEO fixes
   
   - HM-001 (charset), HM-002 (viewport), HM-006 (canonical self-ref)
   - IL-003 (rel=noopener × 4)
   - PF-003 (preconnect fonts)
   - IX-001 (robots.txt généré)
   ...
   
   Findings: <list of IDs>
   Audit: <audit_at timestamp>
   
   Co-Authored-By: tseo <[email protected]>"
   

6. Met à jour <project>/.tseo/applied.md avec les IDs + commit SHA.

---

Sous-phase B — Auto-risky (review individuelle)

Pour tous les findings avec tier: "auto-risky" ET previously_applied: false :

Pour chaque finding (un par un) :

1. Affiche le contexte :

   Finding <id> : <title>
   
   Axe       : <axis>
   Confidence: <confidence>
   Evidence  :
     - <file>:<line> — <snippet>
     - ...
   
   Diff proposé :
   <diff au format unified diff, lisible>
   

2. Demande validation par finding : "Appliquer ce fix ?" (Oui / Non / Skip et voir le suivant)

   • Oui → applique + commit individuel.
   • Non → SKIP, on passe au suivant. Le finding restera dans findings.json mais avec skipped_at_apply: <timestamp>.
   • Skip → idem Non.

3. Applique le fix (mêmes types que Sous-phase A) avec en plus, si applicable :

   • Création de nouveau fichier (ex: SitemapController.php, sitemap.blade.php) : Write avec le boilerplate.
   • Modification de routes/web.php : Edit pour ajouter une Route::get(...).
   • Restructuration de tags (ex: <div class="navbar"> → <nav class="navbar">) : Edit unique.

4. Commit individuel :

   git add <files>
   git commit -m "tseo: apply <id> — <short title>
   
   <description courte du changement>
   
   Evidence:
   - <file>:<line>
   
   Co-Authored-By: tseo <[email protected]>"
   

5. Met à jour applied.md au fil de l'eau (un par un).

Cas particulier : IX-003 (génération sitemap dynamique)

Ce finding crée 3 fichiers (SitemapController.php, sitemap.blade.php, routes/web.php modif) ET ajoute des TODOs dans manual-todos.md (modèles à indexer). Le commit groupe les 3 fichiers du sandbox, et le TODO doit être créé dans le même run pour que l'utilisateur sache qu'il doit compléter le contrôleur.

---

Sous-phase C — Manuel (TODOs + boilerplates)

Pour tous les findings avec tier: "manual" ET previously_applied: false :

1. Génère / append <project>/.tseo/manual-todos.md :

   # TODOs manuels — <YYYY-MM-DD>
   
   Items qui nécessitent une intervention humaine (contenu textuel, choix produit, configuration serveur).
   tseo a positionné les emplacements et les boilerplates ; à toi de remplir.
   
   ## Prioritaires (severity high)
   
   ### HM-005 — Meta description par page
   
   tseo a inséré la structure dans `resources/views/layouts/app.blade.php:14` :
   ```blade
   <meta name="description" content="@yield('meta_description', '')">
   

   Pour chaque vue listée ci-dessous, ajoute une @section('meta_description', '<texte>') (70-160 caractères, unique par page) :

   • resources/views/audit/create.blade.php — page /
   • resources/views/audit/show.blade.php — page /audit/{audit}
   • ...

   HM-007 — OG image

   Crée public/og-default.png (1200×630, format PNG ou JPG, < 8 Mo). Une fois créé, <meta property="og:image"> dans le layout pointera dessus automatiquement.

   JL-001 — Schema Organization (à compléter)

   tseo a inséré le boilerplate dans resources/views/layouts/app.blade.php:XX. À compléter :

   • name: <answers.site_name fourni>
   • logo: URL absolue du logo (au moins 112×112, format PNG/JPG)
   • sameAs: profils sociaux officiels (Twitter, LinkedIn, etc.)

   Standard (severity medium)

   IL-004 — Anchor texts génériques

   ...

   IM-001 — Alt manquants sur images

   • resources/views/audit/show.blade.php:45 — <img src=...> sans alt. Ajouter alt="<description>".
   • ...

   Configuration serveur (à vérifier hors code)

   IX-006 — X-Robots-Tag (Apache/Nginx)

   ...

   SC-004 — HSTS

   ...

2. Pour les findings avec fix.boilerplate (ex: JSON-LD Organization) : appliquer le boilerplate dans le code puis lister le TODO.

   • Le boilerplate écrit dans le sandbox compte comme une modification → commit séparé par boilerplate :

     git commit -m "tseo: insert <id> boilerplate (manual completion required)
     
     Boilerplate inséré dans <file>. Champs à compléter listés dans .tseo/manual-todos.md.
     
     Co-Authored-By: tseo <[email protected]>"
     

3. Met à jour applied.md avec les findings dont le boilerplate a été inséré (statut "boilerplate-only, awaits manual completion").

---

Format final de <project>/.tseo/applied.md

# Findings appliqués par tseo

## Audit du <YYYY-MM-DD HH:MM>

### Auto-safe (commit <SHA>)

- HM-001 — Charset déclaré
- HM-002 — Viewport déclaré
- HM-006 — Canonical self-ref
- IL-003 — rel="noopener" × 4
- IX-001 — robots.txt créé

### Auto-risky (1 commit par finding)

- IX-003 — Sitemap dynamique (commit <SHA>)
  - `app/Http/Controllers/SitemapController.php` (créé)
  - `resources/views/sitemap.blade.php` (créé)
  - `routes/web.php` (route ajoutée)
  - TODO dans `manual-todos.md` : compléter la liste des modèles à itérer.

### Boilerplates manuels (commit <SHA>)

- JL-001 — Organization Schema (boilerplate inséré, valeurs à compléter)

### Skipped

- IX-005 — Routes paramétriques privées en noindex (utilisateur a refusé le diff)

### Already applied (audits précédents)

- HM-003 — lang="fr" (appliqué le 2026-04-25, commit abc1234)

---

Règles d'arrêt

• Working tree sale → STOP avant toute modif.
• findings.json absent → STOP, lance /seo-audit.
• Aucun finding actionnable (tous previously_applied) → STOP avec message "Tout déjà appliqué."
• Si Edit échoue sur > 30% des findings auto-safe → STOP, "Trop d'erreurs, revérifier la cohérence du code (un fichier a été modifié manuellement entre l'audit et l'apply ?)".

Restitution finale

Affiche à l'utilisateur :

✓ Apply terminé.

Auto-safe       : <X> appliqués (commit <SHA>)
Auto-risky      : <Y> appliqués (commits <SHA1>, <SHA2>, ...) — <Z> skippés
Boilerplates    : <W> insérés (commit <SHA>)
Skippés         : <V> (mtime changé ou utilisateur a refusé)

Items à compléter manuellement : <U> dans .tseo/manual-todos.md

Pour vérifier visuellement : `php artisan serve` puis ouvre les pages clefs.
Pour rollback un fix particulier : `git revert <SHA>`.
Pour relancer un audit : `/seo-audit` (mode incrémental, ne refera pas ce qui est déjà appliqué).