Système d'extensions

Le Labo du Yeti embarque un système d'extensions complet, inspiré de l'architecture plugin de WordPress mais conçu pour Node 22 / ESM. Une extension est un dossier autonome installé sous extensions/installed/<id>/, déclaré par un manifeste extension.json, chargé au boot et capable d'ajouter des routes API, de s'abonner à des événements (hooks), d'écrire dans un stockage clé-valeur isolé, d'injecter des entrées dans la sidebar admin et d'enregistrer ses propres capabilities dans la matrice de droits.

Tout passe par un contexte injecté filtré selon les permissions déclarées : une extension n'a jamais accès au filesystem du CMS, ni aux modules privés (services, DB, etc.), ni aux secrets (clé Anthropic, SMTP, JWT_SECRET, hash de tokens). Elle voit uniquement les helpers que son manifest autorise explicitement.

Architecture générale

Chaque extension est représentée à trois niveaux :

• Filesystem — extensions/installed/<id>/ contient extension.json, un éventuel package.json, et un dossier server/ avec routes.js et/ou hooks.js.
• Base de données — 3 tables SQLite : extensions (manifest, statut, version, erreur de chargement), extension_settings (clé-valeur de configuration UI) et extension_data (clé-valeur générique).
• Runtime — un contexte ext est construit au démarrage, ses routes sont montées sous /api/ext/<id> et ses listeners de hooks sont abonnés au bus.

Le cycle de vie d'une extension est strict :

Le manifest extension.json

Le manifest est le point d'entrée déclaratif de toute extension. Il est validé strictement à l'installation (id en kebab-case, version semver, types corrects).

{
  "id": "hello-world",
  "name": "Hello World",
  "version": "1.0.0",
  "description": "Extension de démonstration : expose un endpoint /api/ext/hello-world/ping et logue chaque build.",
  "author": "Le Labo du Yeti",
  "min_cms_version": "0.1.0",
  "permissions": ["storage.read", "storage.write", "logs.write"],
  "hooks": ["build.after"],
  "sidebar": [
    { "label": "Hello World", "icon": "sparkles", "section": "CONFIGURATION", "to": "/ext/hello-world" }
  ],
  "pages": [
    { "path": "/page", "title": "Hello World" }
  ]
}

Champs du manifest

Permissions disponibles

Le contexte ext.* est filtré par les permissions déclarées dans manifest.permissions. Si une permission n'est pas listée, le helper correspondant n'existe tout simplement pas sur l'objet ext (accès = undefined). À l'installation, l'utilisateur valide explicitement la liste via un écran de confirmation humanisé.

Lecture du contenu CMS

Services & métadonnées

Runtime de l'extension

Contexte injecté ext

Chaque extension exporte une fonction register(ext) appelée au chargement. L'objet ext regroupe tout ce que l'extension peut utiliser :

Hooks du core

Le bus d'événements (backend/src/services/hooks-service.js) supporte deux patterns : les événements (emit, fire-and-forget en série) et les filtres (applyFilters, transformation chaînée du payload). Les listeners sont awaités en série ; une exception est loggée mais ne casse pas la chaîne.

Hooks événements

Hooks filtres (transformation)

Pattern filtre : chaque listener reçoit le payload et peut retourner une version modifiée. Si rien n'est retourné, le payload précédent est conservé. Le résultat final est la sortie du dernier listener.

Storage & settings

Chaque extension dispose de deux espaces KV isolés (clés composites (extension_id, key)) :

• Storage (table extension_data) — données runtime, statistiques internes, caches. À la désinstallation, supprimé en cascade.
• Settings (table extension_settings) — configuration utilisateur exposée dans l'UI. Auto-rendue si l'extension déclare manifest.settings_schema.

// Storage : compteur de builds
const n = (ext.storage.get('build_count') || 0) + 1;
ext.storage.set('build_count', n);
ext.logger.info(`Build #${n} terminé`);

// Settings : lire une config utilisateur
const endpoint = ext.settings.get('webhook_url');
if (endpoint) await fetch(endpoint, { method: 'POST', body: '...' });

Les valeurs sont sérialisées en JSON automatiquement (string, number, boolean, object, array). Les FOREIGN KEY ... ON DELETE CASCADE garantissent un nettoyage propre à la désinstallation.

Sidebar dynamique

Une extension peut injecter des entrées dans la sidebar admin via manifest.sidebar. Format d'une entrée :

{
  "label": "Hello World",
  "icon": "sparkles",
  "section": "CONFIGURATION",
  "to": "/ext/hello-world"
}

• label — texte affiché dans la sidebar.
• icon — nom de l'icône (jeu d'icônes du CMS).
• section — CONTENU, MARKETING ou CONFIGURATION. L'utilisateur peut surcharger via la modale Configurer (extension_settings.sidebar_section_override).
• to — route React. Pour une page custom, utiliser /ext/<id> qui charge une iframe pointant vers GET /api/ext/<id>/page.

Capabilities (matrice de droits)

Une extension peut enregistrer ses propres capabilities dans la matrice owner pour bénéficier du même contrôle d'accès que les features du core. L'id est automatiquement préfixé par ext.<extension-id>. pour éviter les conflits.

ext.capabilities.register({
  id: 'webp_convert',                                // → ext.webp-auto-converter.webp_convert
  label: 'Conversion WebP auto',
  group: 'Extension : WebP Auto Converter',         // défaut : "Extension : <name>"
  defaults: { admin: true, webmaster: true, editor: false }
});

La feature apparaît immédiatement dans la matrice owner sous /admin/permissions et peut être activée/désactivée par rôle. Côté backend, l'extension peut vérifier l'accès via les helpers exposés par capabilities-service.js.

Workflow d'installation

L'installation d'une extension passe par deux endpoints exposés sous /api/extensions (auth + role owner|admin|webmaster + capability extensions) :

1. POST /api/extensions/inspect

Upload du zip (max 10 Mo, mimetype strict .zip). Le backend extrait dans un dossier temporaire, valide le manifest et retourne un preview :

{
  "manifest": { "id": "hello-world", "name": "Hello World", "version": "1.0.0", ... },
  "permissions_humanized": [
    "Lire et écrire le stockage interne de l'extension",
    "Écrire dans les logs du CMS",
    "S'abonner à l'événement build.after"
  ],
  "already_installed": false,
  "files_summary": { "routes": true, "hooks": true, "package_json": true }
}

L'UI affiche une modale de confirmation listant chaque permission en clair (jamais d'identifiants techniques bruts à l'utilisateur final).

2. POST /api/extensions

Confirmation côté utilisateur → install réelle :

1. Extraction du zip vers extensions/installed/<id>/ avec garde anti zip slip.
2. Si package.json présent : exécution npm install --omit=dev --no-audit --no-fund dans le dossier de l'extension. Le binaire npm est résolu via le sibling de process.execPath (Plesk-safe).
3. Insertion dans la table extensions avec statut installed, version, copie du manifest.
4. Auto-activation : appel de activateExtension(id) qui monte les routes, abonne les hooks et bascule en active.
5. Log type=extension action=installed dans la table logs.

Autres endpoints

Pour la liste détaillée des middlewares (auth, capability, multer), voir API REST → /api/extensions.

Guide : créer sa première extension

Cet exemple reprend l'extension de référence extensions/installed/hello-world/ livrée avec le CMS et l'enrichit pour démontrer toutes les capacités du système.

Étape 1 — Structure du dossier

my-extension/
├── extension.json          ← manifest (obligatoire)
├── package.json            ← optionnel (deps npm)
└── server/
    ├── routes.js           ← export default register(ext) → ext.router.*
    └── hooks.js            ← export default register(ext) → ext.hooks.on(...)

Étape 2 — Le manifest

{
  "id": "blog-auto-poster",
  "name": "Blog Auto Poster",
  "version": "1.0.0",
  "description": "Publie automatiquement un article de blog après chaque build.",
  "author": "Acme",
  "min_cms_version": "0.1.0",
  "permissions": [
    "storage.read",
    "storage.write",
    "logs.write",
    "cms.blog.read",
    "cms.blog.write"
  ],
  "hooks": ["build.after"],
  "sidebar": [
    { "label": "Auto Poster", "icon": "rocket", "section": "MARKETING", "to": "/ext/blog-auto-poster" }
  ]
}

Étape 3 — Routes API

Le fichier server/routes.js exporte une fonction register(ext). Les routes définies sur ext.router sont automatiquement préfixées par /api/ext/blog-auto-poster.

// server/routes.js
export default function register(ext) {
  ext.router.get('/status', (req, res) => {
    const lastPost = ext.storage.get('last_post_at') || null;
    const totalPosts = ext.storage.get('total_posts') || 0;
    res.json({ ok: true, lastPost, totalPosts });
  });

  ext.router.post('/trigger', async (req, res) => {
    try {
      const article = await ext.cms.blog.createArticle({
        title: 'Article auto — ' + new Date().toISOString(),
        status: 'draft',
        categories: ['actualites'],
      });
      ext.storage.set('total_posts', (ext.storage.get('total_posts') || 0) + 1);
      ext.storage.set('last_post_at', new Date().toISOString());
      ext.logger.info('Article auto créé', { id: article.id });
      res.json({ ok: true, article });
    } catch (err) {
      ext.logger.error('Création article échouée', { error: err.message });
      res.status(500).json({ ok: false, error: err.message });
    }
  });

  ext.logger.info('blog-auto-poster routes loaded');
}

Étape 4 — Hooks

Le fichier server/hooks.js abonne l'extension aux événements du core :

// server/hooks.js
export default function register(ext) {
  ext.hooks.on('build.after', async ({ mode, summary } = {}) => {
    // Publier un article récap après chaque build full
    if (mode !== 'full') return;

    const last = ext.storage.get('last_build_post_at');
    const now = Date.now();
    if (last && now - last < 24 * 3600 * 1000) return; // 1/jour max

    const article = await ext.cms.blog.createArticle({
      title: `Build du ${new Date().toLocaleDateString('fr-FR')}`,
      status: 'published',
    });
    ext.storage.set('last_build_post_at', now);
    ext.logger.info(`Build #${mode} → article publié`, { article_id: article.id, summary });
  });
}

Étape 5 — Déclarer une capability

Pour que les rôles non-owner puissent contrôler l'accès à l'auto-poster, on enregistre une capability au boot :

// server/hooks.js (ajouter dans register)
ext.capabilities.register({
  id: 'auto_post',
  label: 'Publication auto de l\'article de build',
  defaults: { admin: true, webmaster: true, editor: false }
});

Étape 6 — Tester en local

1. Place le dossier dans extensions/installed/blog-auto-poster/.
2. Redémarre le CMS : le loader scanne extensions/installed/*, valide le manifest et active l'extension.
3. Vérifie le statut dans /extensions (UI) : ligne active, aucun champ error.
4. Test endpoint : curl http://localhost:3000/api/ext/blog-auto-poster/status (avec un cookie JWT valide).
5. Déclenche un build pour vérifier que le hook fire correctement et qu'un article est publié.

Étape 7 — Packager en zip

# Depuis le dossier parent de l'extension
Compress-Archive -Path .\blog-auto-poster\* -DestinationPath .\blog-auto-poster-v1.0.0.zip

Le zip est ensuite installable via l'UI /extensions → Installer ou via l'API. La structure attendue dans l'archive est exactement le contenu du dossier (pas de dossier racine englobant).

Exemple de référence : hello-world

Livré avec le CMS sous extensions/installed/hello-world/, sert de squelette minimal pour démarrer.

extension.json

{
  "id": "hello-world",
  "name": "Hello World",
  "version": "1.0.0",
  "description": "Extension de démonstration : expose un endpoint /api/ext/hello-world/ping et logue chaque build.",
  "author": "Le Labo du Yeti",
  "min_cms_version": "0.1.0",
  "permissions": ["storage.read", "storage.write", "logs.write"],
  "hooks": ["build.after"]
}

server/routes.js

export default function register(ext) {
  ext.router.get('/ping', (req, res) => {
    res.json({
      ok: true,
      extension: ext.id,
      version: ext.manifest.version,
      message: 'Hello from extension !',
      timestamp: new Date().toISOString(),
    });
  });

  ext.router.get('/count', (req, res) => {
    const n = (ext.storage.get('ping_count') || 0) + 1;
    ext.storage.set('ping_count', n);
    res.json({ ping_count: n });
  });

  ext.logger.info('Hello World extension loaded');
}

server/hooks.js

export default function register(ext) {
  ext.hooks.on('build.after', async ({ mode, summary } = {}) => {
    const n = (ext.storage.get('build_count') || 0) + 1;
    ext.storage.set('build_count', n);
    ext.logger.info(`Build #${n} terminé (mode=${mode || 'n/a'})`);
  });
}

Extensions livrées avec le CMS

• hello-world — ping + compteur de builds. Squelette de démarrage.
• webp-auto-converter — s'abonne au filtre media.before_save et convertit les images en WebP via sharp avant écriture disque.
• surefeedback-connector — s'abonne au filtre render.html et injecte un snippet HTML (SureFeedback, BugHerd, Marker.io, etc.) juste avant </body>.

Bonnes pratiques

• Demander le strict minimum de permissions. L'utilisateur valide chaque permission à l'install — une extension trop gourmande est refusée.
• Toujours préfixer les clés storage par un namespace fonctionnel (ex. cache.last_run, stats.daily_count) — facilite le débogage et l'export.
• Capturer les exceptions dans les listeners de hooks : une erreur est loggée mais ne casse pas la chaîne. Évite de bloquer un build à cause d'une extension défaillante.
• Versionner correctement (semver) : le CMS expose min_cms_version pour signaler une incompatibilité.
• Tester la désinstallation : storage + settings sont purgés en cascade, mais si l'extension a créé des fichiers hors de son dossier, ils restent. À éviter — toujours écrire via ext.storage ou ext.cms.media.upload.

Références

• backend/src/services/extensions-service.js — loader, install/uninstall, validation manifest.
• backend/src/services/extension-context.js — construction du contexte filtré par permissions.
• backend/src/services/extension-cms-api.js — surface ext.cms.*, sanitization des champs sensibles.
• backend/src/services/hooks-service.js — bus pub/sub + filtres.
• backend/src/routes/extensions.js — endpoints REST /api/extensions.
• extensions/installed/hello-world/ — exemple de référence.
• Base de données — schéma des tables extensions, extension_settings, extension_data.
• Authentification & RBAC — détails capabilities et matrice owner.