@mtldev514/retro-portfolio-engine 1.0.0 → 1.1.2

package/README.md

@@ -1,408 +1,300 @@
-# @retro-portfolio/engine
+# 🎨 Site-as-a-Package Engine
 
-[![npm version](https://badge.fury.io/js/%40retro-portfolio%2Fengine.svg)](https://www.npmjs.com/package/@retro-portfolio/engine)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Un moteur de site web autonome qui récupère son contenu depuis un repo distant et se construit automatiquement. Concept **Site-as-a-Package** : le code du moteur est séparé des données.
 
-**Site-as-a-Package** 🎨 Un moteur de portfolio rétro que vous installez via NPM. Vous fournissez vos données, le package fournit tout le reste.
+## 🚀 Concept
 
-## 🎯 Concept
+Au lieu d'avoir un site avec du contenu figé, ce repo contient uniquement :
 
-Au lieu de cloner un repo complet, vous **installez un package NPM** qui contient tout le moteur (HTML, CSS, JS, admin). Vous gardez uniquement **vos données** dans votre repo.
+1. **Le moteur de rendu** (HTML, CSS, JS)
+2. **Un script de build** qui récupère les données distantes
+3. **Une GitHub Action** qui automatise tout
 
-### Avantages
+Les **données, traductions et configurations** sont stockées dans un repo séparé. À chaque build, le moteur récupère la dernière version du contenu.
 
-✅ **Un seul repo** pour l'utilisateur (juste ses données)
-✅ **Mises à jour faciles** via `npm update`
-✅ **Pas de merge conflicts** pour récupérer les nouvelles features
-✅ **Workflow simple** : `npm install` → `npm run build`
-✅ **Admin inclus** pour gérer le contenu visuellement
+## 📁 Architecture
 
----
-
-## 🚀 Quick Start
-
-### Pour créer votre portfolio
-
-```bash
-# 1. Créer un nouveau portfolio
-npx @retro-portfolio/engine init mon-portfolio
-cd mon-portfolio
-
-# 2. Installer les dépendances
-npm install
-
-# 3. Lancer le serveur de dev
-npm run dev
-
-# 4. Ouvrir http://localhost:8000
-```
-
-C'est tout ! 🎉
-
----
-
-## 📦 Installation dans un projet existant
-
-```bash
-npm install @retro-portfolio/engine
 ```
-
-Puis ajoutez les scripts dans votre `package.json` :
-
-```json
-{
-  "scripts": {
-    "build": "retro-portfolio build",
-    "dev": "retro-portfolio dev",
-    "admin": "retro-portfolio admin"
-  }
-}
-```
-
----
-
-## 📁 Structure de votre projet
-
-Après `init`, votre projet contient **uniquement vos données** :
-
-```
-mon-portfolio/
-├── package.json          (dépendance: @retro-portfolio/engine)
-├── config/               (VOS configurations)
+retro-portfolio-engine/          (Ce repo - Le moteur)
+├── index.html                   Squelette HTML
+├── style.css, fonts.css         Styles
+├── js/
+│   ├── manifest-loader.js       Charge le manifest distribué
+│   ├── i18n.js, render.js       Modules du moteur
+│   └── ...
+├── build.sh                     Script de build avec cache
+├── manifest.json                Configuration du data repo
+└── .github/workflows/
+    └── build-and-deploy.yml     Automatisation GitHub
+
+retro-portfolio-data/            (Repo séparé - Les données)
+├── manifest.json                Point d'entrée
+├── config/
 │   ├── app.json
 │   ├── languages.json
 │   └── categories.json
-├── data/                 (VOTRE contenu)
+├── data/
 │   ├── painting.json
-│   └── projects.json
-├── lang/                 (VOS traductions)
-│   ├── en.json
-│   └── fr.json
-└── assets/               (VOS images, etc.)
+│   └── ...
+└── lang/
+    ├── en.json
+    └── fr.json
 ```
 
-**Pas de code du site** dans votre repo ! Tout vient du package NPM.
-
----
-
-## 🛠️ Commandes
-
-### `retro-portfolio init [directory]`
+## 🔧 Installation
 
-Crée un nouveau portfolio avec les templates de données.
+### 1. Cloner le repo moteur
 
 ```bash
-# Créer dans le dossier actuel
-retro-portfolio init
-
-# Créer dans un nouveau dossier
-retro-portfolio init mon-portfolio
-
-# Forcer l'écrasement
-retro-portfolio init --force
+git clone https://github.com/YOUR_USERNAME/retro-portfolio-engine.git
+cd retro-portfolio-engine
 ```
 
-### `retro-portfolio build`
+### 2. Configurer le manifest
 
-Génère le site statique en fusionnant le moteur avec vos données.
+Éditez `manifest.json` et changez les URLs :
 
-```bash
-# Build standard
-npm run build
-
-# Spécifier le dossier de sortie
-retro-portfolio build --output public
-
-# Watch mode (rebuild automatique)
-retro-portfolio build --watch
+```json
+{
+  "dataRepository": {
+    "owner": "YOUR_USERNAME",
+    "repo": "retro-portfolio-data",
+    "branch": "main",
+    "baseUrl": "https://raw.githubusercontent.com/YOUR_USERNAME/retro-portfolio-data/main/"
+  }
+}
 ```
 
-**Ce qui se passe** :
-1. Le package copie ses fichiers engine (HTML, CSS, JS)
-2. Il fusionne avec vos fichiers `config/`, `data/`, `lang/`
-3. Génère un site complet dans `dist/`
-
-### `retro-portfolio dev`
-
-Lance un serveur de développement local.
+### 3. Build local (avec cache)
 
 ```bash
-npm run dev
+# Build normal (utilise le cache si disponible)
+./build.sh
 
-# Port personnalisé
-retro-portfolio dev --port 3000
+# Force le re-téléchargement complet
+./build.sh --force
 
-# Ouvrir automatiquement le navigateur
-retro-portfolio dev --open
+# Tester localement
+cd dist
+python3 -m http.server 8000
+# Ouvrir http://localhost:8000
 ```
 
-### `retro-portfolio admin`
+### 4. Déploiement automatique sur GitHub Pages
 
-Lance l'interface d'administration pour gérer votre contenu.
+1. **Activer GitHub Pages** dans les paramètres du repo :
+   - Settings → Pages
+   - Source : **GitHub Actions**
 
-```bash
-npm run admin
+2. **Configurer le secret (optionnel)** :
+   - Settings → Secrets → Actions
+   - Ajouter `MANIFEST_URL` si votre manifest est ailleurs
 
-# Port personnalisé
-retro-portfolio admin --port 5001
+3. **Déclencher un build** :
+   - Push sur `main` → build automatique
+   - Actions → Build and Deploy Site → Run workflow
 
-# Ouvrir automatiquement le navigateur
-retro-portfolio admin --open
-```
+## 🎯 Utilisation
 
-**Interface admin** : Ajoutez/modifiez votre contenu visuellement, uploadez des images, gérez les traductions.
+### Mode 1 : Build automatique (recommandé)
 
----
+GitHub Action se déclenche automatiquement :
 
-## 🔄 Workflow Complet
+- ✅ À chaque push sur `main`
+- ✅ Tous les jours à minuit (récupère les nouvelles données)
+- ✅ Manuellement depuis l'onglet Actions
 
-### 1️⃣ Setup initial
+### Mode 2 : Build manuel
 
 ```bash
-npx @retro-portfolio/engine init mon-portfolio
-cd mon-portfolio
-npm install
-```
-
-### 2️⃣ Configuration
+# Build avec cache (rapide)
+./build.sh
 
-Éditez vos fichiers de config :
+# Build complet (ignore le cache)
+./build.sh --force
 
-```bash
-# Configurez votre site
-nano config/app.json
+# Build avec manifest custom
+./build.sh --manifest https://example.com/manifest.json
 
-# Ajoutez vos catégories
-nano config/categories.json
+# Options avancées
+./build.sh --help
 ```
 
-### 3️⃣ Ajout de contenu
+## 🔄 Mettre à jour le contenu
 
-**Option A** : Via l'admin (recommandé)
+### Option A : Modifier le repo de données
 
-```bash
-npm run admin
-# Ouvrir http://localhost:5001/admin.html
-# Upload images, ajouter descriptions, etc.
-```
+1. Modifier les fichiers dans `retro-portfolio-data/`
+2. Commit & push
+3. (Optionnel) Déclencher un rebuild du moteur
 
-**Option B** : Édition manuelle JSON
+### Option B : Utiliser un webhook
 
-```bash
-nano data/painting.json
-```
+Configurez le repo de données pour notifier le moteur :
 
-### 4️⃣ Preview local
+```yaml
+# Dans retro-portfolio-data/.github/workflows/notify.yml
+on:
+  push:
+    branches: [main]
 
-```bash
-npm run dev
-# Ouvrir http://localhost:8000
+jobs:
+  notify-engine:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger rebuild
+        run: |
+          curl -X POST \
+            -H "Authorization: token ${{ secrets.PAT_TOKEN }}" \
+            https://api.github.com/repos/YOUR_USERNAME/retro-portfolio-engine/dispatches \
+            -d '{"event_type": "data-updated"}'
 ```
 
-### 5️⃣ Build pour production
+## 🛡️ Sécurité et Bonnes Pratiques
 
-```bash
-npm run build
-# → génère dist/
-```
+### ✅ CORS
 
-### 6️⃣ Déploiement
+`raw.githubusercontent.com` envoie automatiquement `Access-Control-Allow-Origin: *`, donc **pas de problème CORS** pour les requêtes GET.
 
-**GitHub Pages** :
+### ✅ Validation des données
 
-```bash
-# Pusher le dossier dist/ sur la branche gh-pages
-git add dist -f
-git commit -m "Deploy"
-git subtree push --prefix dist origin gh-pages
+Le `manifest-loader.js` valide la structure du manifest :
+
+```javascript
+validateManifest(manifest) {
+    const required = ['version', 'dataRepository', 'structure'];
+    // Validation stricte
+}
 ```
 
-Ou utilisez la GitHub Action fournie (voir section Déploiement).
+### ✅ Cache intelligent
 
----
+Le script `build.sh` utilise un cache local (`.cache/`) :
 
-## 🎨 Personnalisation
+- ⚡ Accélère les builds répétés
+- 🔄 TTL de 1 heure par défaut
+- 🔨 Option `--force` pour forcer le refresh
 
-### Ajouter un thème custom
+### ✅ Sanitisation
 
-Créez `assets/custom-theme.css` :
+Tous les contenus HTML sont sanitisés pour éviter les XSS :
 
-```css
-:root {
-  --primary-color: #your-color;
-  --font-family: 'Your-Font', monospace;
+```javascript
+sanitizeHTML(str) {
+    const temp = document.createElement('div');
+    temp.textContent = str;
+    return temp.innerHTML;
 }
 ```
 
-Le build l'inclura automatiquement !
-
-### Ajouter des pages custom
+## 📊 Fonctionnalités
 
-Créez `pages/about.html` dans votre projet. Le moteur le détectera au build.
+### ✨ Avantages
 
----
+- **🔄 Toujours à jour** : Récupère la dernière version du contenu à chaque build
+- **📦 Léger** : Le repo moteur est quasi vide
+- **🌍 Multi-langues** : Support natif de plusieurs langues
+- **⚡ Performant** : Cache intelligent, build optimisé
+- **🔒 Sécurisé** : Validation, sanitisation, pas d'eval()
+- **🚀 Zero-config** : Push et c'est déployé
 
-## 🔄 Mettre à jour le moteur
+### 🎨 Personnalisation
 
-Pour récupérer les dernières features du moteur :
+Vous pouvez modifier :
 
-```bash
-npm update @retro-portfolio/engine
+- `style.css` : Apparence visuelle
+- `js/render.js` : Logique de rendu
+- `manifest.json` : Source des données
 
-# Ou version spécifique
-npm install @retro-portfolio/engine@latest
-```
-
-**Aucun conflit de merge** ! Vos données restent intactes.
+## 🐛 Dépannage
 
----
+### Le build échoue
 
-## 🌐 Déploiement
+```bash
+# Vérifier que jq est installé
+which jq
 
-### GitHub Pages (automatique)
+# Tester manuellement le manifest
+curl https://raw.githubusercontent.com/YOUR_USERNAME/retro-portfolio-data/main/manifest.json
 
-Créez `.github/workflows/deploy.yml` :
+# Build en mode verbose
+bash -x build.sh
+```
 
-```yaml
-name: Deploy to GitHub Pages
+### Les données ne se mettent pas à jour
 
-on:
-  push:
-    branches: [main]
+```bash
+# Forcer le re-téléchargement
+./build.sh --force
 
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-
-      - run: npm install
-      - run: npm run build
-
-      - uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./dist
+# Vider le cache
+rm -rf .cache
+./build.sh
 ```
 
-Push sur `main` → Site déployé automatiquement ! ✨
+### GitHub Action échoue
 
-### Netlify / Vercel
-
-**Build command** : `npm run build`
-**Publish directory** : `dist`
-
----
+1. Vérifier que GitHub Pages est activé
+2. Vérifier les permissions dans Settings → Actions → Workflow permissions
+3. Consulter les logs dans Actions → Build and Deploy
 
 ## 📚 Documentation Avancée
 
-### Structure du package
+### Structure du Manifest
 
-```
-@retro-portfolio/engine/
-├── engine/               (Code du site - copié au build)
-│   ├── index.html
-│   ├── style.css
-│   ├── js/
-│   └── admin/
-├── scripts/              (Scripts Node.js)
-│   ├── build.js
-│   ├── serve.js
-│   └── admin.js
-├── bin/
-│   └── cli.js            (CLI retro-portfolio)
-└── templates/            (Templates pour init)
-```
-
-### API de données
-
-Format des fichiers JSON :
-
-**data/painting.json** :
 ```json
 {
-  "items": [
-    {
-      "id": "unique-id",
-      "title": {
-        "en": "Sunset",
-        "fr": "Coucher de soleil"
-      },
-      "description": {
-        "en": "A beautiful sunset",
-        "fr": "Un magnifique coucher de soleil"
-      },
-      "image": "https://cloudinary.com/...",
-      "date": "2026-01-15"
+  "version": "1.0.0",
+  "dataRepository": {
+    "type": "github",
+    "baseUrl": "https://raw.githubusercontent.com/..."
+  },
+  "structure": {
+    "config": {
+      "app": "config/app.json",
+      "languages": "config/languages.json"
+    },
+    "data": {
+      "painting": "data/painting.json"
+    },
+    "lang": {
+      "en": "lang/en.json"
     }
-  ]
-}
-```
-
-**lang/en.json** :
-```json
-{
-  "header_title": "My Portfolio",
-  "nav_painting": "Paintings",
-  "footer_copy": "© 2026 Your Name"
+  }
 }
 ```
 
----
-
-## 🐛 Dépannage
-
-### Le build échoue
-
-```bash
-# Vérifier que les dossiers requis existent
-ls -la config/ data/ lang/
-
-# Réinstaller le package
-rm -rf node_modules
-npm install
-```
+### API du ManifestLoader
 
-### L'admin ne démarre pas
+```javascript
+// Initialiser
+await ManifestLoader.init('./manifest.json');
 
-L'admin nécessite Python 3 et Flask :
+// Récupérer des URLs
+const appConfigUrl = ManifestLoader.getConfigUrl('app');
+const paintingUrl = ManifestLoader.getDataUrl('painting');
+const frTransUrl = ManifestLoader.getLangUrl('fr');
 
-```bash
-pip install flask flask-cors
+// Lister les langues disponibles
+const langs = ManifestLoader.getAvailableLanguages();
 ```
 
-### Les images ne s'affichent pas
-
-Vérifiez que vos URLs d'images sont complètes (Cloudinary, etc.) ou placez-les dans `assets/`.
-
----
-
 ## 🤝 Contribution
 
-Ce package est open source ! Pour contribuer :
+Les contributions sont les bienvenues ! Pour contribuer :
 
-1. Fork le repo [retro-portfolio-engine](https://github.com/YOUR_USERNAME/retro-portfolio-engine)
-2. Créez une branche feature
-3. Soumettez une Pull Request
-
----
+1. Fork le projet
+2. Créer une branche (`git checkout -b feature/amazing`)
+3. Commit vos changements
+4. Push et créer une Pull Request
 
 ## 📄 Licence
 
-MIT © Alex
+MIT License - Utilisation libre
 
 ---
 
-## 🔗 Liens
-
-- [Documentation](https://github.com/YOUR_USERNAME/retro-portfolio-engine)
-- [NPM Package](https://www.npmjs.com/package/@retro-portfolio/engine)
-- [Issues](https://github.com/YOUR_USERNAME/retro-portfolio-engine/issues)
-- [Exemples](https://github.com/YOUR_USERNAME/retro-portfolio-examples)
-
----
+**Fait avec 💜 par Alex**
 
-**Fait avec 💜 pour la communauté créative**
+🔗 [Demo](https://YOUR_USERNAME.github.io/retro-portfolio-engine/)
+🐛 [Issues](https://github.com/YOUR_USERNAME/retro-portfolio-engine/issues)