ben-to/README.md

Ben-to

Constructeur de bento pixel-art, multi-plateforme (web + Android + iOS).

Stack

• Web: SolidJS (Vite)
• Mobile: Capacitor
• Données: catalogue embarqué, progression locale (offline, sans compte cloud en V1)
• Qualité: Vitest + Playwright + Axe + Lighthouse

Partage des URLs recette (/r/…) et métadonnées Open Graph : voir docs/seo-recipe-sharing.md.

Matomo (analytics + bandeau cookies) : voir docs/matomo-analytics.md et apps/web/.env.example.

Démarrage

npm install
npm run pipeline:recipes
npm run dev:web

Les recettes (fichiers *.lang.bentext), les couvertures (ressources/public/, placeholders dans ressources/recipe-placeholder-covers/), les sprites ingrédients (ressources/public/ingredients.png, ingredient-sprites.bentext, source Aseprite sous ressources/source/) sont versionnés dans ce dépôt — pas de synchronisation avec un serveur de contenus externe.

Après modification des sources, régénérer le catalogue :

npm run pipeline:recipes

Règles d’édition des fichiers bentext : .cursor/rules/recipes-bentext.mdc.

Tester l'app web

À exécuter depuis la racine du dépôt.

Même chaîne que la CI (ESLint + TypeScript, Vitest avec couverture sur les packages métier, Playwright + Axe, pas de duplication unit/int séparée dans ce script) :

npm run pipeline:recipes   # régénère le catalogue si besoin (dev / e2e)
npm run test:ci

Voir CONTRIBUTING.md (hook pre-commit, tickets, Gherkin @int-*).

Les e2e (npm run test:e2e ou via test:ci) s’appuient sur playwright.config.ts : le serveur Vite est démarré avec npm run dev:web si aucun n’écoute déjà sur le port (voir reuseExistingServer).

Pour régénérer les GIF du tour d’accueil (fichiers dans apps/web/public/tour/, hors test:ci) : npm run tour:capture — nécessite ffmpeg sur la machine (playwright.tour-capture.config.ts).

Contrôles ciblés sur le paquet apps/web (lint + types du front uniquement) :

npm run lint -w apps/web
npm run typecheck -w apps/web

Build de production du front :

npm run pipeline:recipes
npm run build:web

Tester sur un téléphone Android (Capacitor)

Le shell natif est dans **apps/mobile** et embarque le build statique **apps/web/dist** (voir apps/mobile/capacitor.config.ts).

Un correctif patch-package (patches/@capacitor-community+sqlite+8.1.0.patch) remplace proguard-android.txt par proguard-android-optimize.txt dans le plugin SQLite (exigence R8 / AGP récents). Il est réappliqué à chaque **npm install** via le script **postinstall**.

Important — répertoire courant : pipeline:recipes, build:web et les scripts mobile:* sont définis dans le **package.json à la racine** du dépôt (ben-to/, là où se trouve ce README). Si vous lancez npm run … depuis **apps/mobile**, npm cherche ces scripts dans le workspace mobile et échoue (Missing script). Vérifiez avec ls package.json : vous devez voir le manifest racine, pas celui du sous-dossier.

Prérequis

• Android Studio (SDK + outils plate-forme).
• Sur le téléphone : Options pour les développeurs activées, puis Débogage USB (câble USB) ou Débogage sans fil (Wi‑Fi) selon votre appareil.

Première fois : ajouter la plateforme Android

Si le dossier **apps/mobile/android/** n’existe pas encore dans votre clone :

cd apps/mobile
npx cap add android
cd ../..

Build du web, sync Capacitor, lancer sur l’appareil

Toujours depuis la racine du dépôt (puis Android Studio s’ouvre sur apps/mobile/android) :

npm install
npm run pipeline:recipes
npm run build:web
npm run mobile:sync
npm run mobile:open:android

(mobile:sync / mobile:open:android appellent le workspace **@ben-to/mobile** ; évite les erreurs du type No workspaces found si le flag -w ne cible pas le bon nom.)

Dans Android Studio : choisir votre téléphone comme cible, puis Run (▶).

En ligne de commande (appareil déjà autorisé / adb devices OK), toujours depuis la racine :

npm run mobile:run:android

Modifier le front sans tout régénérer (optionnel)

Pour charger l’UI depuis votre PC sur le réseau local (évite un build:web à chaque changement), vous pouvez temporairement renseigner dans apps/mobile/capacitor.config.ts un bloc server: { url: "http://VOTRE_IP_LAN:3000", cleartext: true } (à retirer avant release), puis lancer le front avec l’écoute réseau :

npm run dev:web -- --host 0.0.0.0

Adaptez le pare-feu / le même Wi‑Fi entre le PC et le téléphone.

Qualité obligatoire

npm run check:quality
npm run test:unit
npm run test:integration
npm run test:e2e

CI / Sécurité

• .github/workflows/ci.yml — qualité, couverture, e2e + artefacts qualité, Lighthouse, assembleDebug Android, rapport PR
• .github/workflows/security.yml — CodeQL, npm audit, Gitleaks (activation upload SARIF)
• .github/workflows/dependency-review.yml — revue des dépendances sur les PR (selon options du dépôt)
• .github/workflows/mobile-release.yml

Publication V1 (web + Android)

Checklist gel release : docs/V1_LAUNCH_CHECKLIST.md.

Déploiement CapRover

• Le dépôt contient Dockerfile et captain-definition pour un déploiement via CapRover (hors GitHub Actions).

Ticketing GitHub

Création rapide des issues MVP :

./scripts/github/create-issues.sh kazerlelutin/ben-to

Tickets post-MVP (builder SOLID, suppression des barrels index, SEO OG recettes) : gabarits sous .github/ISSUE_TEMPLATE/ (04–06), corps dans docs/tickets/, création en masse après gh auth login :

./scripts/github/create-post-mvp-issues.sh