Publier

Du dossier d'un plugin au bouton Installer de chaque Hodi : tester, essayer sur un Hodi de test, construire le fichier, puis le faire vérifier et signer par le registre des plugins.

En bref

Un plugin passe par quatre étapes avant d'arriver chez les gens. Les trois premières se font seul, sur sa machine. La dernière passe par le mainteneur de Hodi.

Le modèle de plugin contient déjà tout : le SDK, les scripts et la CI. Il n'y a rien à installer en plus.

Tester

Ce que fait un test

Un test lance la partie serveur du plugin comme Hodi la lance :

1. Le SDK construit le plugin.
2. Il le charge dans le même bac à sable que Hodi.
3. Il appelle ses routes avec les mêmes vérifications que Hodi.

Autour, il y a un petit Hodi en mémoire : un foyer, son admin, et des remplaçants pour les sites, les e-mails, les notifications et l'IA. Un test n'envoie donc jamais rien à personne. Il tourne pareil sur sa machine et dans la CI.

Un exemple

Le modèle de plugin a déjà ce fichier. Il demande la route POST /hello et regarde la réponse :

import assert from 'node:assert/strict'
import { after, describe, it } from 'node:test'
import { testPlugin } from '@hodi-app/plugin-sdk/testing'

describe('my-plugin', async () => {
  const hodi = await testPlugin('.', {
    settings: {
      greeting: 'Salut'
    }
  })
  after(() => hodi.stop())

  it('answers a child too', async () => {
    const child = await hodi.addPerson({
      name: 'Zoé',
      kind: 'child'
    })
    const answer = await hodi.route('POST /hello', {
      as: child
    })
    assert.equal(answer.status, 200)
  })
})

Pour lancer les tests :

npm test

La CI du modèle les relance à chaque push. Un plugin qui passe ses tests se comporte pareil une fois installé dans un vrai Hodi.

Les options de testPlugin

testPlugin('.') prend le dossier du plugin. Le deuxième argument, facultatif, prépare le petit Hodi :

Ce que le petit Hodi permet

Essayer sur un Hodi de test

Un test vérifie la partie serveur. Pour voir aussi la partie web, il faut un vrai Hodi : le mode développeur y installe le plugin, puis le remet à jour à chaque enregistrement.

Ce qu'il faut

• Un Hodi à soi, sur sa machine par exemple (http://localhost:3000).
• Être l'admin de son serveur.

Un Hodi de test évite de mélanger ses essais avec les données de son foyer.

Les étapes

1. Ouvrir Serveur › Plugins sur le Hodi de test.
2. Activer le mode développeur : Hodi affiche un code, une seule fois.
3. Copier ce code.
4. Dans le dossier du plugin, lancer la commande ci-dessous en remplaçant LE_CODE.
5. Laisser la commande tourner pendant le travail.

npx hodi-plugin dev --server http://localhost:3000 --code LE_CODE

Ce qui se passe ensuite

À chaque enregistrement d'un fichier, la commande :

1. reconstruit le plugin ;
2. l'envoie au Hodi de test ;
3. attend que Hodi redémarre avec la nouvelle version (quelques secondes) ;
4. affiche le journal du plugin dans le terminal.

Dans Hodi, le plugin porte le badge En développement. Ses pages s'affichent même sans signature, et il garde ses données d'une version à l'autre. Ctrl+C arrête la commande.

Construire

Le fichier du plugin

npm run build

La commande écrit un seul fichier, dist/<id>-<version>.hodi-plugin. Par exemple dist/hello-world-0.1.0.hodi-plugin. C'est ce fichier que les gens installent.

L'installer à la main

N'importe quel admin peut installer ce fichier, même sur un serveur qu'il ne gère que depuis son navigateur :

1. Ouvrir Serveur › Plugins.
2. Cliquer sur Ajouter un plugin et choisir le fichier.
3. Lire ce que Hodi montre : le nom, la version et les permissions.
4. Confirmer l'installation.

Ce que l'admin voit avant d'installer

Hodi regarde si le fichier est signé, et le dit à l'admin :

Les permissions réservées aux plugins signés sont listées dans Le manifeste.

Être vérifié

Pourquoi une signature

Une signature dit à Hodi qui a fait un plugin. Hodi ne fait confiance qu'à une seule clé : celle de son mainteneur.

Les pages d'un plugin tournent dans la page de Hodi, avec la session de la personne connectée. C'est pour ça que seul un plugin signé, ou celui qui est en développement, peut afficher les siennes.

Les étapes

1. Mettre le plugin dans un dépôt GitHub public.
2. Publier une release v<version> (par exemple v0.1.0) avec son fichier .hodi-plugin.
3. Ajouter le plugin au registre des plugins par une pull request.
4. Le mainteneur lit le code du plugin.
5. S'il suit les règles de Hodi, il signe cette version et accepte la pull request.

Dans le modèle de plugin, pousser un tag v0.1.0 suffit pour l'étape 2 : la CI construit le fichier et crée la release toute seule.

L'entrée dans le registre

Le registre est une simple liste, le fichier plugins.json. Une entrée demande deux champs, et la commande npm run index du registre remplit le reste depuis la release :

{
  "repo": "https://github.com/me/hodi-plugin-hello-world",
  "version": "0.1.0"
}

Le README du registre détaille les commandes à lancer avant la pull request.

Ensuite

• Le plugin apparaît dans Serveur › Plugins › Disponibles de chaque Hodi.
• Il s'y installe en un clic.
• Chaque nouvelle version passe par une nouvelle pull request.

Cette nouvelle version est relue, puis signée à son tour.

Les règles de Hodi

Le mainteneur vérifie chacune de ces règles avant de signer un plugin.