@mtldev514/retro-portfolio-engine 1.0.0

package/README.md

@@ -0,0 +1,408 @@
+# @retro-portfolio/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)
+
+**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
+
+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.
+
+### Avantages
+
+✅ **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
+
+---
+
+## 🚀 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)
+│   ├── app.json
+│   ├── languages.json
+│   └── categories.json
+├── data/                 (VOTRE contenu)
+│   ├── painting.json
+│   └── projects.json
+├── lang/                 (VOS traductions)
+│   ├── en.json
+│   └── fr.json
+└── assets/               (VOS images, etc.)
+```
+
+**Pas de code du site** dans votre repo ! Tout vient du package NPM.
+
+---
+
+## 🛠️ Commandes
+
+### `retro-portfolio init [directory]`
+
+Crée un nouveau portfolio avec les templates de données.
+
+```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
+```
+
+### `retro-portfolio build`
+
+Génère le site statique en fusionnant le moteur avec vos données.
+
+```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
+```
+
+**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.
+
+```bash
+npm run dev
+
+# Port personnalisé
+retro-portfolio dev --port 3000
+
+# Ouvrir automatiquement le navigateur
+retro-portfolio dev --open
+```
+
+### `retro-portfolio admin`
+
+Lance l'interface d'administration pour gérer votre contenu.
+
+```bash
+npm run admin
+
+# Port personnalisé
+retro-portfolio admin --port 5001
+
+# Ouvrir automatiquement le navigateur
+retro-portfolio admin --open
+```
+
+**Interface admin** : Ajoutez/modifiez votre contenu visuellement, uploadez des images, gérez les traductions.
+
+---
+
+## 🔄 Workflow Complet
+
+### 1️⃣ Setup initial
+
+```bash
+npx @retro-portfolio/engine init mon-portfolio
+cd mon-portfolio
+npm install
+```
+
+### 2️⃣ Configuration
+
+Éditez vos fichiers de config :
+
+```bash
+# Configurez votre site
+nano config/app.json
+
+# Ajoutez vos catégories
+nano config/categories.json
+```
+
+### 3️⃣ Ajout de contenu
+
+**Option A** : Via l'admin (recommandé)
+
+```bash
+npm run admin
+# Ouvrir http://localhost:5001/admin.html
+# Upload images, ajouter descriptions, etc.
+```
+
+**Option B** : Édition manuelle JSON
+
+```bash
+nano data/painting.json
+```
+
+### 4️⃣ Preview local
+
+```bash
+npm run dev
+# Ouvrir http://localhost:8000
+```
+
+### 5️⃣ Build pour production
+
+```bash
+npm run build
+# → génère dist/
+```
+
+### 6️⃣ Déploiement
+
+**GitHub Pages** :
+
+```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
+```
+
+Ou utilisez la GitHub Action fournie (voir section Déploiement).
+
+---
+
+## 🎨 Personnalisation
+
+### Ajouter un thème custom
+
+Créez `assets/custom-theme.css` :
+
+```css
+:root {
+  --primary-color: #your-color;
+  --font-family: 'Your-Font', monospace;
+}
+```
+
+Le build l'inclura automatiquement !
+
+### Ajouter des pages custom
+
+Créez `pages/about.html` dans votre projet. Le moteur le détectera au build.
+
+---
+
+## 🔄 Mettre à jour le moteur
+
+Pour récupérer les dernières features du moteur :
+
+```bash
+npm update @retro-portfolio/engine
+
+# Ou version spécifique
+npm install @retro-portfolio/engine@latest
+```
+
+**Aucun conflit de merge** ! Vos données restent intactes.
+
+---
+
+## 🌐 Déploiement
+
+### GitHub Pages (automatique)
+
+Créez `.github/workflows/deploy.yml` :
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+
+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
+```
+
+Push sur `main` → Site déployé automatiquement ! ✨
+
+### Netlify / Vercel
+
+**Build command** : `npm run build`
+**Publish directory** : `dist`
+
+---
+
+## 📚 Documentation Avancée
+
+### Structure du package
+
+```
+@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"
+    }
+  ]
+}
+```
+
+**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
+```
+
+### L'admin ne démarre pas
+
+L'admin nécessite Python 3 et Flask :
+
+```bash
+pip install flask flask-cors
+```
+
+### 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 :
+
+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
+
+---
+
+## 📄 Licence
+
+MIT © Alex
+
+---
+
+## 🔗 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 💜 pour la communauté créative**

package/bin/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * Retro Portfolio CLI
+ * Main command-line interface for the package
+ */
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs-extra');
+
+const program = new Command();
+
+// Import scripts
+const build = require('../scripts/build');
+const serve = require('../scripts/serve');
+const admin = require('../scripts/admin');
+const init = require('../scripts/init');
+
+program
+  .name('retro-portfolio')
+  .description('Retro Portfolio Site Engine')
+  .version(require('../package.json').version);
+
+// Init command - Create new portfolio
+program
+  .command('init [directory]')
+  .description('Initialize a new portfolio with data templates')
+  .option('-f, --force', 'Overwrite existing files')
+  .action(async (directory, options) => {
+    try {
+      await init(directory || '.', options);
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Build command - Generate static site
+program
+  .command('build')
+  .description('Build the static site from your data')
+  .option('-o, --output <dir>', 'Output directory', 'dist')
+  .option('-w, --watch', 'Watch for changes and rebuild')
+  .action(async (options) => {
+    try {
+      await build(options);
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Serve command - Local development server
+program
+  .command('dev')
+  .alias('serve')
+  .description('Start local development server')
+  .option('-p, --port <number>', 'Port number', '8000')
+  .option('-o, --open', 'Open browser automatically')
+  .action(async (options) => {
+    try {
+      await serve(options);
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Admin command - Launch admin interface
+program
+  .command('admin')
+  .description('Start admin interface for managing content')
+  .option('-p, --port <number>', 'Port number', '5001')
+  .option('-o, --open', 'Open browser automatically')
+  .action(async (options) => {
+    try {
+      await admin(options);
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Deploy command - Deploy to GitHub Pages
+program
+  .command('deploy')
+  .description('Deploy site to GitHub Pages')
+  .option('-b, --branch <name>', 'Deployment branch', 'gh-pages')
+  .option('-d, --dir <path>', 'Build directory', 'dist')
+  .action(async (options) => {
+    console.log(chalk.yellow('Deploy command coming soon!'));
+    console.log('For now, use GitHub Actions or push dist/ manually.');
+  });
+
+// Parse arguments
+program.parse(process.argv);
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}