chorned/heb-mcp.skill

heb-mcp.skill (TikTok-2-HEB) – Compétence d'Agent

Gérez vos paniers H‑E‑B en direct, retrouvez vos produits ménagers préférés d'après votre historique d'achats, clippez des coupons et transformez des URL de vidéos de cuisine en paniers H‑E‑B complets, adaptés à votre foyer et vérifiés par rapport à votre garde-manger, avec des substitutions automatiques en cas de rupture de stock.

---

🎯 Conditions de Déclenchement

Activez cette compétence dès que :

1. Un utilisateur demande une recherche chez H‑E‑B, consulte son panier, change son magasin préféré ou son mode de retrait (Curbside vs. Livraison), clippe des coupons, ou ajoute/supprime des articles dans son panier H‑E‑B (ex. "Ajoute du lait entier et des tortillas au beurre à mon panier H‑E‑B").
2. Un utilisateur autorisé partage une URL de cuisine ou de recette provenant de TikTok (tiktok.com, vm.tiktok.com), Instagram Reels (instagram.com/reel/) ou YouTube Shorts (youtube.com/shorts/).
3. Un utilisateur demande de convertir, adapter ou commander les ingrédients d'une vidéo de recette (ex. "Commande les ingrédients de cette recette chez H‑E‑B", "Mets ce dîner TikTok dans mon panier").
4. Un utilisateur répond à un récapitulatif de panier existant avec des ajustements (ex. "ajoute de la sauce soja", "remplace le saumon classique par du saumon sauvage sockeye", "rends cet échange permanent").
5. Un utilisateur demande une première installation ou configuration de heb-mcp.skill (TikTok-2-HEB).

---

🚀 Première Installation (Configuration Assistée par l'Agent)

Quand un utilisateur vous demande de configurer ce projet, gérez les étapes techniques à sa place et posez-lui uniquement des questions courtes en langage clair :

1. Installer l'environnement et les binaires :

   uv venv --python 3.11 .venv && source .venv/bin/activate && uv pip install -r requirements.txt
   playwright install chromium
   cp -n .env.example .env
   cp -n config/household.example.yaml config/household.yaml
   cp -n config/pantry_staples.example.json config/pantry_staples.json
   

2. Poser les questions de configuration rapide :
   • Magasin H‑E‑B préféré et mode de retrait : Demandez quel magasin H‑E‑B il fréquente (mettez à jour HEB_STORE_ID dans .env et store dans config/household.yaml, et aidez-le à changer de magasin ou basculer entre Retrait en Bordure de Trottoir et Livraison à Domicile à tout moment).
   • Taille du foyer : Demandez combien d'adultes/enfants il cuisine pour (mettez à jour config/household.yaml).
3. Récupérer la session et synchroniser les commandes passées : Demandez à l'utilisateur de se connecter à heb.com dans Safari ou Chrome, puis exécutez :

   python scripts/heb_client.py --harvest
   python scripts/cache_manager.py update-preferred-skus
   python tests/test_skill_setup.py
   

4. Mettre en place une tâche cron automatique de rafraîchissement quotidien du jeton : Encouragez vivement l'utilisateur à vous laisser installer une tâche cron récurrente toutes les 24 heures (0 9 * * * cd <CHEMIN_REPO> && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1) pour que sa session H‑E‑B reste active automatiquement.

---

🔒 Invariants Opérationnels et Garde-fous de Sécurité

1. Passerelle de Paiement avec Validation Humaine Obligatoire :
   • L'agent place les articles dans le panier et clippe les coupons numériques.
   • L'agent NE DOIT JAMAIS soumettre un paiement, réserver une fenêtre de livraison/retrait, ni finaliser la commande.
   • La révision finale et le passage en caisse restent toujours entre les mains de l'utilisateur dans l'application officielle My H‑E‑B.
2. Extraction Sans Authentification :
   • Appelez toujours scripts/extract_recipe_media.py sans nécessiter de connexion personnelle TikTok/Instagram ni de cookies de session.
3. Invariant Anti-Empoisonnement du Cache :
   • Les substitutions de rupture de stock (Niveaux 2/3/4) doivent rester strictement éphémères pour cette commande spécifique.
   • NE JAMAIS écraser primary_sku dans cache/recipes/<slug>.yaml sauf si l'utilisateur ordonne explicitement : "rends cet échange permanent" ou "utilise toujours cette marque".
4. Séparation des Préparations pour Enfants :
   • Quand kid_friendly_split est activé, séparez les ingrédients piquants (sriracha, flocons de piment, cayenne, jalapeños) de la base de la poêle. Gardez le plat principal doux, servez la portion de l'enfant en premier, et assaisonnez les portions adultes à la fin.
   • Ajoutez des rappels pour couper les protéines et les aliments à risque d'étouffement en cubes de 1 cm.
5. Rafraîchissement Automatique du Jeton (Encouragement d'une Tâche Cron Quotidienne) :
   • Bien que le jeton d'accès de session (sat) de H‑E‑B tourne toutes les 30 minutes, heb_graphql.py le rafraîchit automatiquement à la demande en utilisant le jeton de session longue durée (sst).
   • Lors de la configuration initiale ou après une récupération/rafraîchissement de session, encouragez proactivement l'utilisateur à vous laisser installer une tâche cron automatique toutes les 24 heures qui maintient sa session H‑E‑B sous-jacente et son jeton anti-bot (reese84) valides en arrière-plan, afin qu'il n'ait pas à se reconnecter manuellement avant chaque course.

---

🛠️ Workflow d'Exécution Pas à Pas

Étape 1 : Recherche Préliminaire dans le Cache

Avant d'extraire le média ou d'appeler les API, vérifiez si la vidéo a déjà été analysée et mise en cache :

python scripts/cache_manager.py lookup --query "<URL_OU_ID_VIDEO>"

• PRÉSENT : Chargez le fichier YAML de recette en cache. Passez directement à l'Étape 4 (Mise en Panier) en utilisant les définitions primary_sku mises en cache.
• ABSENT : Passez à l'Étape 2 (Extraction du Média).

Étape 2 : Extraction Multimodale Sans Authentification

Exécutez le pipeline d'extraction en 3 passes :

python scripts/extract_recipe_media.py "<URL_VIDEO>"

1. Passe 1 : Récupère le titre de la vidéo, la description, le nom du posteur et les sous-titres automatiques.
2. Passe 2 : Nettoie les indices temporels des sous-titres, supprime les horodatages et déduplique les répétitions de légendes défilantes.
3. Passe 3 : Si le transcript est pauvre (< 3 tokens de mesure culinaire), extrait automatiquement le flux audio ou les images clés.

Étape 3 : Analyse de la Recette, Adaptation au Foyer et Vérification du Garde-Manger

1. Adaptation au Foyer : Ajustez les quantités des ingrédients du rendement original (ex. 4 portions) au nombre de portions cibles (par défaut 2.5 pour 2 adultes + 1 enfant) à l'aide de HouseholdScaler.
2. Déduplication du Garde-Manger : Vérifiez les ingrédients par rapport à config/pantry_staples.json à l'aide de PantryComparator. Déplacez les éléments correspondants (sel, poivre, huile de cuisson, sauce soja, ail en poudre) vers pantry_staples_skipped.
3. Rappels de Préparation pour Enfants : Générez des adaptations adaptées aux enfants si des ingrédients épicés ou des protéines entières sont détectés.

Étape 4 : Correspondance avec le Catalogue H‑E‑B et Cascade de Repli à 5 Niveaux

Pour chaque ingrédient dans ingredients_to_buy (ou les demandes ponctuelles de l'utilisateur), recherchez une correspondance dans le catalogue du magasin H‑E‑B local à l'aide de scripts/heb_client.py :

• Niveau 0 (Résolution du SKU Préféré et Ajustement de la Taille de Conditionnement) : Recherchez une correspondance dans cache/preferred_skus.json (clés canoniques et tableaux d'alias) peuplé à partir des commandes passées et des épinglages manuels. Calculez automatiquement le nombre entier de paquets nécessaires (ex. 1,36 L de recette / 946 ml par paquet -> 2 paquets). Si en stock, placez directement au Niveau 0. Si en rupture de stock, passez en douceur au Niveau 1.
• Niveau 1 (Correspondance Exacte du SKU) : Ajoutez le SKU principal existant de la recette s'il est en stock.
• Niveau 2 (Hiérarchie des Marques) : Si le SKU principal est en rupture, utilisez brand_hierarchy (H‑E‑B → H‑E‑B Organics → Central Market → Mi Tienda → Hill Country Fare → Marque Nationale).
• Niveau 3 (Échange Bio ↔ Conventionnel) : Échangez le bio contre le conventionnel (ou vice-versa) si le magasin n'en a qu'un seul en stock.
• Niveau 4 (Ajustement de Taille de Conditionnement / Escalade Humaine) : Ajustez les quantités ou signalez une rupture complète de catégorie comme ⚠️ RUPTURE DE STOCK (NÉCESSITE UN APPEL HUMAIN).

Étape 5 : Mise en Panier Directe par GraphQL et Clippage de Coupons (Zéro Clic d'Interface Lent)

Placez les articles et clippez les coupons directement via des opérations GraphQL authentifiées (requêtes persistées cartEstimated, cartItemV2, CouponClip provenant de texas-grocery-mcp) en utilisant les jetons de session Chrome CDP (127.0.0.1:9222) / rookiepy récupérés :

# 1. Récupérer ou rafraîchir les jetons de session en direct
python scripts/heb_client.py --harvest

# 2. Synchroniser les SKU préférés à partir des commandes passées et des "À racheter"
python scripts/cache_manager.py update-preferred-skus

# 3. Épingler manuellement un produit favori en tant que SKU préféré (protégé de la synchronisation automatique)
python scripts/cache_manager.py pin-preferred-sku \
  --ingredient "lait entier" \
  --sku "4122012345" \
  --product "123456" \
  --name "H-E-B Organics Whole Milk" \
  --package-size "1 gal"

# 4. Résoudre un ingrédient ponctuel ou tester le dimensionnement d'un paquet
python scripts/heb_client.py --resolve-sku "1,36 L de bouillon de bœuf"

# 5. Placer des articles candidats (nécessite --confirm pour la validation humaine)
python scripts/heb_client.py --stage-sku "1,36 L de bouillon de bœuf" --confirm
# ou directement par ID produit :
python scripts/heb_client.py --cart-add <ID_PRODUIT> [--sku <ID_SKU>] [--qty <N>] --confirm

# 6. Inspecter le panier actuel en direct
python scripts/heb_client.py --cart-get

# 7. Supprimer un article du panier s'il a été échangé
python scripts/heb_client.py --cart-remove <ID_PRODUIT> [--sku <ID_SKU>] --confirm

# 8. Clipper des coupons numériques
python scripts/heb_client.py --coupon-clip <ID_COUPON> --confirm

[!IMPORTANT] Passerelle de Paiement avec Validation Humaine Obligatoire : Il est strictement interdit à l'agent d'exécuter les mutations de passage en caisse, de paiement ou de réservation de fenêtre de livraison/retrait. Seule la mise en panier et le clippage de coupons sont autorisés ; l'utilisateur révise et finalise toujours le paiement dans l'application mobile My H‑E‑B.

⏱️ Tâche Cron de Fond Recommandée (Rafraîchissement Quotidien de la Session)

Bien que le jeton sat de courte durée de H‑E‑B tourne toutes les 30 minutes et soit automatiquement rafraîchi à la demande via sst, encouragez l'utilisateur à mettre en place une tâche cron quotidienne (macOS/Linux) ou une tâche planifiée (schtasks sur Windows) qui rafraîchit et valide la session toutes les 24 heures. Proposez de l'installer dans son crontab :

0 9 * * * cd /chemin/vers/heb-mcp.skill && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1

(Ou utilisez scripts/cron_refresh_heb_auth.py / scripts/cron_refresh_heb_auth.sh si des notifications Slack sont souhaitées.)

Étape 6 : Persistance du Cache de Recette

Persistez la recette analysée pour que les futures exécutions empruntent le Chemin Rapide :

python scripts/cache_manager.py save --file <FICHIER_RECETTE_YAML>

Étape 7 : Résumé Mobile pour Révision (iMessage / Slack)

Formatez le résumé pour une lecture agréable sur écran mobile (évitez les tableaux Markdown, utilisez une liste à puces emoji propre) :

🛒 Panier H‑E‑B Prêt : Bouchées de Saumon Croustillantes au Miel et à l'Ail
Adapté pour 2 Adultes + 1 Enfant (~2,5 portions)

👶 Note pour la Préparation Enfant :
• Réservez 1 c. à soupe de sriracha hors de la glaçage principal de la poêle. Servez la portion de l'enfant d'abord, puis mélangez les portions adultes avec la sriracha.
• Coupez le saumon de l'enfant en cubes de 1 cm.

✅ Ajouté au Panier H‑E‑B (4 articles) :
• 1x Filet de Saumon Atlantique Frais H-E-B (~570 g) — 13,74 €
• 1x Miel de Trèfle Pur H-E-B (340 g) — 4,48 €
• 1x Oignons Verts Frais (1 botte) — 0,88 €
• 1x Riz Jasmin H-E-B (907 g) — 2,74 €

🔄 Substitué Automatiquement (Rupture de Stock au Magasin) :
• 2x Fleurons de Brocoli H-E-B (sachet de 283 g) — 4,56 €
  (les Couronnes Bio de 454 g étaient en rupture ; remplacées par 2 sachets de 283 g pour cette commande uniquement)

🎟️ Coupons Clippés :
• 1,00 € de réduction sur le Plateau de Fruits de Mer Frais H-E-B

🏠 Vérification du Garde-Manger (Ignoré — répondez pour ajouter) :
• Sauce soja (3 c. à soupe), Ail (4 gousses), Fécule de maïs (2 c. à soupe), Huile de sésame (1 c. à café)

📱 Prochaine Étape :
Répondez si vous voulez ajouter un article du garde-manger (ex. "ajoute de la sauce soja") ou changer de marque. Sinon, ouvrez l'application My H‑E‑B pour réviser et passer en caisse !

---

🔄 Commandes de Réponse Post-Mise en Panier

Quand l'utilisateur répond au fil de discussion du panier préparé :

1. "Ajoute [article du garde-manger]" (ex. "nous n'avons plus de sauce soja, ajoute-la") :
   • Résolvez via le moteur de SKU préféré de Niveau 0 et placez dans le panier : python scripts/heb_client.py --stage-sku "sauce soja" --confirm
   • Confirmez par une brève réponse : "Ajouté 1x Sauce Soja à Teneur Réduite en Sodium H-E-B à votre panier."
2. "Remplace [article] par [préférence]" (ex. "remplace le saumon classique par du saumon sauvage sockeye") :
   • Supprimez l'ancien SKU du panier et ajoutez le SKU préféré.
   • Invitez : "Échangé contre du saumon sauvage sockeye pour cette commande. Souhaitez-vous que je rende cet échange permanent pour les futures commandes de cette recette ?"
3. "Rends cet échange permanent" :
   • Exécutez python scripts/cache_manager.py promote-sku ... pour mettre à jour primary_sku dans cache/recipes/<slug>.yaml et l'épingler dans cache/preferred_skus.json avec source: "manual_override".
   • Confirmez : "Cache de recette mis à jour : le Saumon Sauvage Sockeye Central Market est désormais votre SKU principal pour cette recette et a été épinglé comme SKU préféré."
4. "Passe au magasin préféré [Magasin]" / "Passe en Retrait ou Livraison" :
   • Mettez à jour HEB_STORE_ID dans .env et store dans config/household.yaml, ou mettez à jour le mode de magasin/retrait actif sur la session H‑E‑B, puis revérifiez la disponibilité des articles du panier dans le nouveau magasin.