retro-portfolio-engine 1.0.0

package/.github/workflows/build-and-deploy.yml

@@ -0,0 +1,105 @@
+name: Build and Deploy Site
+
+on:
+  # Manual trigger
+  workflow_dispatch:
+    inputs:
+      force_rebuild:
+        description: 'Force rebuild (ignore cache)'
+        required: false
+        type: boolean
+        default: false
+
+  # Scheduled rebuild (daily at midnight UTC)
+  schedule:
+    - cron: '0 0 * * *'
+
+  # Trigger on push to main
+  push:
+    branches:
+      - main
+
+  # Webhook from data repository (requires setup)
+  repository_dispatch:
+    types: [data-updated]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Prevent concurrent deployments
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 📦 Checkout Engine Repository
+        uses: actions/checkout@v4
+
+      - name: 🔧 Install Dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq curl
+
+      - name: 🏗️ Build Site
+        run: |
+          # Set execute permission
+          chmod +x build.sh
+
+          # Run build script
+          if [ "${{ github.event.inputs.force_rebuild }}" = "true" ]; then
+            ./build.sh --force
+          else
+            ./build.sh
+          fi
+        env:
+          MANIFEST_URL: ${{ secrets.MANIFEST_URL || 'https://raw.githubusercontent.com/YOUR_USERNAME/retro-portfolio-data/main/manifest.json' }}
+
+      - name: 📊 Build Summary
+        run: |
+          echo "### 🎨 Build Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Build Date:** $(date -u +"%Y-%m-%d %H:%M:%S UTC")" >> $GITHUB_STEP_SUMMARY
+
+          if [ -f dist/build-info.json ]; then
+            echo "**Manifest Version:** $(jq -r '.version' dist/build-info.json)" >> $GITHUB_STEP_SUMMARY
+            echo "**Data Source:** $(jq -r '.dataSource' dist/build-info.json)" >> $GITHUB_STEP_SUMMARY
+            echo "**Cache Used:** $(jq -r '.cacheUsed' dist/build-info.json)" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Files Generated:**" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          ls -lh dist/ >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+
+      - name: 📤 Upload Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: 🚀 Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+      - name: ✅ Deployment Complete
+        run: |
+          echo "### 🎉 Deployment Successful!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Site URL:** ${{ steps.deployment.outputs.page_url }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Your site has been successfully deployed!" >> $GITHUB_STEP_SUMMARY

package/ADMIN_SETUP.md

@@ -0,0 +1,306 @@
+# 🔧 Configuration de l'Admin pour Site-as-a-Package
+
+## 📋 Vue d'ensemble
+
+Pour utiliser votre interface admin avec le système Site-as-a-Package, vous avez **deux options** :
+
+### **Option A : Admin dans le repo de données** (Recommandé)
+- Admin hébergé dans `retro-portfolio-data`
+- Modifie directement les fichiers data/
+- Commit et push automatique vers GitHub
+- Déclenche rebuild du site engine
+
+### **Option B : Admin local séparé**
+- Admin sur votre machine uniquement
+- Utilise l'API Python existante
+- Vous push manuellement vers GitHub
+
+---
+
+## 🚀 Option A : Admin dans le Data Repo (Recommandé)
+
+### Architecture
+
+```
+retro-portfolio-data/
+├── config/
+├── data/
+├── lang/
+├── admin/                    ← Nouveau dossier
+│   ├── index.html           (admin.html)
+│   ├── admin.css
+│   ├── admin.js             (logique admin)
+│   └── api/
+│       └── github-sync.php  (ou .js pour serverless)
+└── .github/workflows/
+    └── notify-engine.yml    (notifie le engine après modification)
+```
+
+### Fonctionnement
+
+1. **Vous modifiez** via l'admin → `retro-portfolio-data.github.io/admin/`
+2. **Admin commit** les changements vers `data/` via GitHub API
+3. **Webhook** notifie `retro-portfolio-engine`
+4. **Engine rebuild** automatiquement avec nouvelles données
+
+### Avantages
+
+✅ Accessible de partout (web-based)
+✅ Pas besoin de Python local
+✅ Git history automatique
+✅ Rebuild automatique du site
+
+### Configuration requise
+
+1. **Personal Access Token (PAT)** avec scope `repo`
+2. **GitHub Pages** activé sur `retro-portfolio-data`
+
+---
+
+## 🛠️ Option B : Admin Local (Simple)
+
+### Architecture
+
+```
+votre-machine/
+├── retro-portfolio-data/     (clone du repo)
+│   ├── config/
+│   ├── data/
+│   └── lang/
+└── admin-local/
+    ├── admin.html
+    ├── admin_api.py          (votre API existante)
+    └── scripts/
+```
+
+### Fonctionnement
+
+1. **Clone** `retro-portfolio-data` localement
+2. **Lancez** `python3 admin_api.py`
+3. **Ouvrez** `admin.html` dans le navigateur
+4. **Modifiez** vos données
+5. **Push manuellement** :
+   ```bash
+   cd retro-portfolio-data
+   git add data/
+   git commit -m "Update content via admin"
+   git push
+   ```
+6. **Rebuild** déclenché automatiquement
+
+### Avantages
+
+✅ Utilise votre admin existant
+✅ Pas de configuration complexe
+✅ Contrôle total
+
+### Inconvénients
+
+❌ Nécessite Python local
+❌ Push manuel requis
+❌ Pas accessible à distance
+
+---
+
+## 🎨 Configuration de l'Option B (Quick Start)
+
+### 1. Préparer le repo de données
+
+```bash
+# Créer et cloner le repo de données
+git clone https://github.com/YOUR_USERNAME/retro-portfolio-data.git
+cd retro-portfolio-data
+
+# Copier vos données existantes
+cp -r ../retro-portfolio/config ./
+cp -r ../retro-portfolio/data ./
+cp -r ../retro-portfolio/lang ./
+
+git add .
+git commit -m "Initial data import"
+git push
+```
+
+### 2. Configurer l'admin local
+
+```bash
+# Créer dossier admin
+mkdir -p admin-local
+
+# Copier admin files
+cp ../retro-portfolio/admin.html admin-local/
+cp ../retro-portfolio/admin.css admin-local/
+cp ../retro-portfolio/admin_api.py admin-local/
+cp -r ../retro-portfolio/scripts admin-local/
+
+# Copier .env (credentials Cloudinary)
+cp ../retro-portfolio/.env admin-local/
+```
+
+### 3. Modifier admin_api.py pour pointer vers le data repo
+
+```python
+# admin-local/admin_api.py
+
+# Modifier les chemins
+DATA_DIR = '../retro-portfolio-data/data'
+CONFIG_DIR = '../retro-portfolio-data/config'
+LANG_DIR = '../retro-portfolio-data/lang'
+```
+
+### 4. Lancer l'admin
+
+```bash
+cd admin-local
+python3 admin_api.py
+
+# Dans un autre terminal
+cd retro-portfolio-data
+python3 -m http.server 8001
+
+# Ouvrir http://localhost:8001/admin-local/admin.html
+```
+
+### 5. Workflow de mise à jour
+
+```bash
+# Après modification via admin
+cd retro-portfolio-data
+
+# Vérifier les changements
+git status
+
+# Commit
+git add data/ lang/
+git commit -m "Update content via admin"
+
+# Push (déclenche rebuild automatique)
+git push
+```
+
+---
+
+## 🌐 Configuration de l'Option A (Avancé)
+
+### 1. Activer GitHub Pages sur le data repo
+
+```bash
+# Dans retro-portfolio-data/
+mkdir -p admin
+cp ../retro-portfolio/admin.html admin/index.html
+cp ../retro-portfolio/admin.css admin/
+
+git add admin/
+git commit -m "Add web-based admin"
+git push
+```
+
+Settings → Pages → Source: `main` branch → `/` (root)
+
+### 2. Créer l'API serverless
+
+```javascript
+// admin/api/sync.js (pour Vercel/Netlify)
+import { Octokit } from "@octokit/rest";
+
+export default async function handler(req, res) {
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  const { category, data, message } = req.body;
+  const PAT = process.env.GITHUB_PAT;
+
+  const octokit = new Octokit({ auth: PAT });
+
+  try {
+    // Get current file content
+    const { data: currentFile } = await octokit.repos.getContent({
+      owner: 'YOUR_USERNAME',
+      repo: 'retro-portfolio-data',
+      path: `data/${category}.json`,
+    });
+
+    // Update file
+    await octokit.repos.createOrUpdateFileContents({
+      owner: 'YOUR_USERNAME',
+      repo: 'retro-portfolio-data',
+      path: `data/${category}.json`,
+      message: message || 'Update via admin',
+      content: Buffer.from(JSON.stringify(data, null, 2)).toString('base64'),
+      sha: currentFile.sha,
+    });
+
+    res.status(200).json({ success: true });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+}
+```
+
+### 3. Adapter admin.html
+
+```javascript
+// Dans admin.html, remplacer les appels API
+
+async function saveData(category, items) {
+  const response = await fetch('/api/sync', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      category,
+      data: { items },
+      message: `Update ${category} via web admin`
+    })
+  });
+
+  if (!response.ok) throw new Error('Failed to save');
+
+  // Déclencher rebuild du engine
+  await triggerRebuild();
+}
+
+async function triggerRebuild() {
+  await fetch('https://api.github.com/repos/YOUR_USERNAME/retro-portfolio-engine/dispatches', {
+    method: 'POST',
+    headers: {
+      'Authorization': `token ${GITHUB_PAT}`,
+      'Accept': 'application/vnd.github+json'
+    },
+    body: JSON.stringify({ event_type: 'data-updated' })
+  });
+}
+```
+
+---
+
+## 🔐 Sécurité
+
+### Pour l'Option A (Web Admin)
+
+1. **Protéger l'admin** avec authentification
+2. **Utiliser des secrets** pour le PAT (variables d'environnement)
+3. **Limiter les permissions** du PAT au strict nécessaire
+
+### Pour l'Option B (Local Admin)
+
+1. **Ne jamais commit** votre `.env` avec credentials
+2. **Ajouter** `.env` au `.gitignore`
+
+---
+
+## 📊 Recommandation
+
+Pour votre cas, je recommande **Option B** car :
+
+✅ Plus simple à mettre en place
+✅ Réutilise votre admin existant
+✅ Pas de configuration serverless
+✅ Contrôle total local
+
+Le workflow devient :
+```
+Modifier via admin local → git push → Rebuild auto du site
+```
+
+Voulez-vous que je vous prépare les scripts pour l'Option B ?

package/README.md

@@ -0,0 +1,300 @@
+# 🎨 Site-as-a-Package Engine
+
+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.
+
+## 🚀 Concept
+
+Au lieu d'avoir un site avec du contenu figé, ce repo contient uniquement :
+
+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
+
+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.
+
+## 📁 Architecture
+
+```
+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/
+│   ├── painting.json
+│   └── ...
+└── lang/
+    ├── en.json
+    └── fr.json
+```
+
+## 🔧 Installation
+
+### 1. Cloner le repo moteur
+
+```bash
+git clone https://github.com/YOUR_USERNAME/retro-portfolio-engine.git
+cd retro-portfolio-engine
+```
+
+### 2. Configurer le manifest
+
+Éditez `manifest.json` et changez les URLs :
+
+```json
+{
+  "dataRepository": {
+    "owner": "YOUR_USERNAME",
+    "repo": "retro-portfolio-data",
+    "branch": "main",
+    "baseUrl": "https://raw.githubusercontent.com/YOUR_USERNAME/retro-portfolio-data/main/"
+  }
+}
+```
+
+### 3. Build local (avec cache)
+
+```bash
+# Build normal (utilise le cache si disponible)
+./build.sh
+
+# Force le re-téléchargement complet
+./build.sh --force
+
+# Tester localement
+cd dist
+python3 -m http.server 8000
+# Ouvrir http://localhost:8000
+```
+
+### 4. Déploiement automatique sur GitHub Pages
+
+1. **Activer GitHub Pages** dans les paramètres du repo :
+   - Settings → Pages
+   - Source : **GitHub Actions**
+
+2. **Configurer le secret (optionnel)** :
+   - Settings → Secrets → Actions
+   - Ajouter `MANIFEST_URL` si votre manifest est ailleurs
+
+3. **Déclencher un build** :
+   - Push sur `main` → build automatique
+   - Actions → Build and Deploy Site → Run workflow
+
+## 🎯 Utilisation
+
+### Mode 1 : Build automatique (recommandé)
+
+GitHub Action se déclenche automatiquement :
+
+- ✅ À chaque push sur `main`
+- ✅ Tous les jours à minuit (récupère les nouvelles données)
+- ✅ Manuellement depuis l'onglet Actions
+
+### Mode 2 : Build manuel
+
+```bash
+# Build avec cache (rapide)
+./build.sh
+
+# Build complet (ignore le cache)
+./build.sh --force
+
+# Build avec manifest custom
+./build.sh --manifest https://example.com/manifest.json
+
+# Options avancées
+./build.sh --help
+```
+
+## 🔄 Mettre à jour le contenu
+
+### Option A : Modifier le repo de données
+
+1. Modifier les fichiers dans `retro-portfolio-data/`
+2. Commit & push
+3. (Optionnel) Déclencher un rebuild du moteur
+
+### Option B : Utiliser un webhook
+
+Configurez le repo de données pour notifier le moteur :
+
+```yaml
+# Dans retro-portfolio-data/.github/workflows/notify.yml
+on:
+  push:
+    branches: [main]
+
+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"}'
+```
+
+## 🛡️ Sécurité et Bonnes Pratiques
+
+### ✅ CORS
+
+`raw.githubusercontent.com` envoie automatiquement `Access-Control-Allow-Origin: *`, donc **pas de problème CORS** pour les requêtes GET.
+
+### ✅ Validation des données
+
+Le `manifest-loader.js` valide la structure du manifest :
+
+```javascript
+validateManifest(manifest) {
+    const required = ['version', 'dataRepository', 'structure'];
+    // Validation stricte
+}
+```
+
+### ✅ Cache intelligent
+
+Le script `build.sh` utilise un cache local (`.cache/`) :
+
+- ⚡ Accélère les builds répétés
+- 🔄 TTL de 1 heure par défaut
+- 🔨 Option `--force` pour forcer le refresh
+
+### ✅ Sanitisation
+
+Tous les contenus HTML sont sanitisés pour éviter les XSS :
+
+```javascript
+sanitizeHTML(str) {
+    const temp = document.createElement('div');
+    temp.textContent = str;
+    return temp.innerHTML;
+}
+```
+
+## 📊 Fonctionnalités
+
+### ✨ 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é
+
+### 🎨 Personnalisation
+
+Vous pouvez modifier :
+
+- `style.css` : Apparence visuelle
+- `js/render.js` : Logique de rendu
+- `manifest.json` : Source des données
+
+## 🐛 Dépannage
+
+### Le build échoue
+
+```bash
+# Vérifier que jq est installé
+which jq
+
+# Tester manuellement le manifest
+curl https://raw.githubusercontent.com/YOUR_USERNAME/retro-portfolio-data/main/manifest.json
+
+# Build en mode verbose
+bash -x build.sh
+```
+
+### Les données ne se mettent pas à jour
+
+```bash
+# Forcer le re-téléchargement
+./build.sh --force
+
+# Vider le cache
+rm -rf .cache
+./build.sh
+```
+
+### GitHub Action échoue
+
+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 Manifest
+
+```json
+{
+  "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"
+    }
+  }
+}
+```
+
+### API du ManifestLoader
+
+```javascript
+// Initialiser
+await ManifestLoader.init('./manifest.json');
+
+// Récupérer des URLs
+const appConfigUrl = ManifestLoader.getConfigUrl('app');
+const paintingUrl = ManifestLoader.getDataUrl('painting');
+const frTransUrl = ManifestLoader.getLangUrl('fr');
+
+// Lister les langues disponibles
+const langs = ManifestLoader.getAvailableLanguages();
+```
+
+## 🤝 Contribution
+
+Les contributions sont les bienvenues ! Pour contribuer :
+
+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 License - Utilisation libre
+
+---
+
+**Fait avec 💜 par Alex**
+
+🔗 [Demo](https://YOUR_USERNAME.github.io/retro-portfolio-engine/)
+🐛 [Issues](https://github.com/YOUR_USERNAME/retro-portfolio-engine/issues)