Développer un module
18/10/2026 · Guide du développeur
Synthèse
Principe : un module est un fichier JavaScript unique, sans import. L'application le charge après contrôle de son empreinte, lui accorde les ports qu'il déclare, affiche ses vues et lance ses automatisations.
- Créer : copier
sdk/modele-module.jsdansmodules/<id>/<id>.js. - Déclarer : besoins, réglages, vues, automatisations, styles.
- Essayer :
essayerModuleetrendreVuefont tourner le module dans Node, sans navigateur ni relais. - Publier :
npm run registreconstruit le registre ; la relecture précède la copie vers paisapp.pro.
Un module ne touche jamais une clé. L'hôte signe, chiffre et publie à sa place.
1. Architecture
Le module suit l'architecture hexagonale d'App-core.
- Cœur : le module décrit ce qu'il fait. Il ne connaît ni NOSTR, ni le navigateur, ni le stockage.
- Ports : seule porte vers l'extérieur. Chaque port a des méthodes nommées et des réponses typées.
- Adaptateurs : l'application réalise les ports au-dessus des relais NOSTR. Les essais les réalisent en mémoire, par
socle/modules/ports-memoire.js. - Même fichier partout : le module essayé dans Node est l'octet près celui que l'application charge.
| Garantie | Mécanisme |
|---|---|
| Provenance | Le fichier vient toujours du registre relu ; un module absent de son index ne se charge pas |
| Intégrité | Empreinte SHA-384 épinglée dans le manifeste et dans l'index, contrôlée avant chaque chargement |
| Moindre droit | L'hôte accorde seulement les ports déclarés, dans un objet figé |
| Aucune clé exposée | Aucun port ne donne une clé ; l'hôte signe et chiffre |
| Aucun accès caché | Le registre refuse import, réseau direct, stockage du navigateur et code fabriqué à la volée |
| Isolement des styles | Chaque sélecteur commence par .m-<id> |
2. Créer un module
2.1 Arborescence
| Fichier | Rôle |
|---|---|
modules/<id>/<id>.js | Le module, fichier unique |
modules/<id>/README.md | Aide courte, reprise par le registre et par paisapp.pro |
modules/<id>/<id>.test.js | Essais node:test |
registre.config.json | Catégorie, auteur, licence et relecture, tenus par les mainteneurs du registre |
2.2 Déclaration
L'export par défaut reçoit paisapp et renvoie paisapp.module({ … }).
export default (paisapp) => {
const { html, montant } = paisapp.outils;
return paisapp.module({
id: 'fidelite', version: '1.0.0', socle: '^0.1',
nom: 'Fidélité', description: 'Compte les commandes livrées de chaque client.',
roles: ['pro'],
besoins: { requis: ['commandes', 'stockage'], facultatifs: ['notifications'] },
reglages: { palier: { type: 'nombre', libelle: 'Commandes avant un cadeau', defaut: 10, min: 1 } },
vues: [{ id: 'clients', titre: 'Clients fidèles', role: 'pro', menu: true, ordre: 80, icone: 'equipe', rendre(ctx) { /* … */ } }],
automatisations: [{ id: 'compter', titre: 'Compter les livraisons', declencheur: 'commande.etape', async executer(d, ports, reglages) { /* … */ } }],
styles: '.m-fidelite .palier { color: var(--pa-couleur-secondaire); }',
});
};
| Champ | Règle |
|---|---|
id | Minuscules, chiffres et tirets ; égal au nom du dossier |
version | Semver ; toute modification publiée exige une nouvelle version |
socle | Intervalle accepté, par exemple ^0.1 |
nom, description | Textes affichés par l'atelier et le registre |
roles | client, pro ; déduits des vues s'ils manquent |
besoins | Ports requis et facultatifs ; un port requis absent laisse le module inactif |
reglages | Schéma typé, voir section 6 |
vues | Écrans du module, voir section 5 |
automatisations | Réactions aux déclencheurs, voir section 4 |
styles | Feuille de 50 000 caractères au plus, sous .m-<id> |
3. Ports
Chaque méthode répond par les formes d'App-core. Une méthode ne lève pas d'exception.
| Forme | Sens |
|---|---|
{ status: 'found', value } | Donnée trouvée ; une liste répond toujours ainsi, vide au besoin |
{ status: 'empty' } | Rien ne correspond |
{ status: 'unavailable' } | Fonction absente de l'application |
{ status: 'done', id } | Écriture faite |
{ status: 'failed', error: { code, message } } | Refus, avec un code |
| Port | Méthodes |
|---|---|
| session | profil() : pubkey, nom, role, entreprise, delegue, delegues, application |
| annuaire | entreprises({ recherche, secteur, zone, limite }), entreprise(pubkey) |
| catalogue | articles({ vendeur, recherche, categorie, geohash, limite, avecIndisponibles }), evenements({ organisateur, depuis, limite }) |
| publication | publierArticle(article), retirerArticle(id), publierEvenement(evenement), retirerEvenement(id) |
| commandes | liste({ role, etat, limite }), detail(commandeId) |
| commande | passer, etape, message, sousTraiter, deleguer |
| panier | contenu(), ajouter({ article, quantite }), changer({ article, quantite }), vider({ vendeur }) : chacune rend { lignes, total, nombre, parVendeur } ; un panier par application |
| stockage | lire(cle), ecrire(cle, valeur), effacer(cle), cles() |
| notifications | avertir({ titre, texte, lien }) |
| navigation | aller('#/…') |
| horloge | maintenant(), synchrone, en secondes |
| journal | ecrire(niveau, message, donnees), synchrone |
- Identités : un client agit avec sa clé personnelle. Le propriétaire agit avec la clé de l'entreprise. Un délégué agit avec sa propre clé et voit seulement les commandes que l'entreprise lui confie.
- Résumé d'une commande :
commandeId,role,vendeur,acheteur,montant,devise,lignes,livraison,adresse,contact,note,parent,etape,date,maj,delegue. L'étape vautnouvelleavant la première étape. L'application peut aussi donnernon-transmise, étape locale et finale d'une commande jamais partie vers une entreprise fermée ; son outiletapeen donne le libellé, « Non transmise ». - Détail : le résumé, plus
historiqueetsousCommandes. - Stockage : chaque module a son propre espace ; une valeur JSON fait 100 000 caractères au plus.
- Référence exacte :
socle/modules/ports-memoire.jsréalise chaque port et sert de spécification exécutable.
4. Déclencheurs
| Déclencheur | Données reçues |
|---|---|
commande.recue | Résumé de la commande, rôle vendeur |
commande.etape | { commande, code, auteur, message } |
commande.message | { commande, texte, auteur } |
sous-commande.etape | { commande, parent, code } : commande est la sous-commande |
minute | { maintenant } |
- Exécution : l'hôte lance les automatisations quand l'application est ouverte. Une erreur reste dans son module.
- Chaînes : une automatisation qui provoque un autre déclencheur est suivie ; la chaîne s'arrête à trois niveaux.
- Retour : la valeur renvoyée par
executersert au journal de l'hôte et aux essais.
5. Vues
5.1 Contexte
| Champ | Rôle |
|---|---|
element | Élément où la vue dessine |
ports, reglages, outils | Ports accordés, réglages contrôlés, outils de rendu |
role | client ou pro |
parametres, requete | Segments après #/m/<module>/<vue>/ et paramètres après ? |
application | Application métier courante, ou null dans l'application Paisapp |
afficher(fragment) | Remplace le contenu de l'élément |
icone(nom, libelle) | Icône de l'hôte en fragment sûr ; sans libellé, elle reste décorative |
aller(chemin) | Ouvre une autre vue |
rafraichir() | Relance rendre |
surChangement(sujet, fn) | Rappel quand commandes, catalogue, evenements, annuaire, panier, session ou modules (manifestes des applications) changent |
reglagesEntreprise(cle) | Dans l'application Paisapp seulement : réglages du module publiés par l'entreprise de cette clé, dans le manifeste le plus récent qu'elle a signé et qui contient le module. Résultat found (valeurs contrôlées comme reglages), empty (aucune application publiée) ou failed. Absente dans une application métier, où reglages sont ceux de l'entreprise, et chez un hôte plus ancien : la vue garde alors reglages |
signal | Signal levé quand l'utilisateur quitte la vue |
5.2 Patron d'une vue
Le gabarit html échappe chaque valeur. La vue dessine par ctx.afficher, écoute une seule fois sur ctx.element et repère ses boutons par data-action. Elle renvoie une fonction de nettoyage.
async rendre(ctx) {
const { html } = ctx.outils;
let message = '';
const dessiner = async () => {
const r = await ctx.ports.commandes.liste({ role: 'vendeur', etat: 'ouvertes' });
const liste = r.status === 'found' ? r.value : [];
ctx.afficher(html`<section class="pa-page m-fidelite">
${message ? html`<p class="pa-alerte pa-alerte-succes" role="status">${message}</p>` : ''}
<ul class="pa-liste">${liste.map((c) => html`<li class="pa-liste-element">${c.commandeId}</li>`)}</ul>
<form data-action="noter"><label class="pa-champ"><span>Note</span><input name="note"></label>
<button class="pa-bouton" type="submit">Enregistrer</button></form>
</section>`);
};
const surEnvoi = async (e) => {
const f = e.target.closest('form[data-action="noter"]');
if (!f) return;
e.preventDefault();
const note = [...f.elements].find((x) => x.name === 'note')?.value ?? '';
await ctx.ports.stockage.ecrire('note', note);
message = 'Note enregistrée.';
await dessiner();
};
ctx.element.addEventListener('submit', surEnvoi);
ctx.surChangement('commandes', dessiner);
await dessiner();
return () => ctx.element.removeEventListener('submit', surEnvoi);
}
- Avis après une attente : une vue abonnée à un sujet peut être redessinée pendant qu'elle attend un port (l'application intègre l'envoi en local avant de l'attendre des relais). Un message écrit ensuite dans un élément trouvé avant l'attente se perd : il est hors de la page. Gardez-le dans une variable qui survit au redessin et écrivez-le dans le gabarit, comme
messageci-dessus ;rafraichir()rappellerendreavec le mêmectx, qui peut donc servir de clé (WeakMap). Les modules commandes 1.0.2, catalogue 1.0.1 et evenements 1.0.1 le font ; l'optionportsdu kit d'essai permet de redessiner la vue pendant l'attente. - Formulaires : lire les champs par
form.elements. Le même code tourne dans le navigateur et dans le faux élément des essais. - Aucun attribut
on…nistyle: la politique de sécurité du contenu les bloque. La mise en forme passe par les classes de l'hôte et lesstylesdu module. - Icônes :
ctx.icone('panier')rend une icône de l'hôte, au trait de l'habillage. - Section d'accueil : une vue
accueil: trues'affiche aussi sur la page d'accueil d'une application métier.ctx.parametresvaut alors['accueil'].
5.3 Vocabulaire CSS de l'hôte
| Classe | Rôle |
|---|---|
pa-page, pa-pile, pa-ligne, pa-grille | Vue, pile verticale, ligne souple, grille de cartes |
pa-titre, pa-sous-titre, pa-texte-doux | Titres et texte secondaire |
pa-carte, pa-carte-image, pa-carte-corps | Carte |
pa-bouton, pa-bouton-secondaire, pa-bouton-discret, pa-bouton-danger | Boutons |
pa-badge, pa-badge-succes, pa-badge-alerte, pa-badge-erreur | Pastilles |
pa-prix | Montant mis en valeur |
pa-liste, pa-liste-element | Liste à lignes |
pa-vide, pa-chargement | État vide, chargement |
pa-alerte, pa-alerte-succes, pa-alerte-erreur | Encadrés |
pa-formulaire, pa-champ, pa-aide, pa-actions | Formulaires |
pa-tableau | Tableau |
pa-etapes, pa-etape, pa-etape-faite, pa-etape-courante | Frise des étapes |
pa-quantite | Choix d'une quantité |
Icônes : accueil, catalogue, panier, commandes, evenement, entreprise, equipe, automatisation, reglages, message, recherche, ajouter, retour.
5.4 Styles
- Chaque sélecteur commence par
.m-<id>. Le registre admet@media,@supportset@container. - Une animation se nomme
m-<id>-…. - Les couleurs, polices et rayons viennent des jetons
var(--pa-*). L'habillage choisi dans l'atelier s'applique alors au module. - Le registre refuse
@import,@font-faceet toute ressource extérieure.
6. Réglages
L'atelier construit le formulaire depuis le schéma. L'hôte contrôle chaque valeur et remplace une valeur refusée par le défaut.
| Type | Valeur | Options du schéma |
|---|---|---|
texte | Texte d'une ligne, 200 caractères par défaut | longueur |
texteLong | Texte de 5 000 caractères par défaut | longueur |
nombre | Nombre fini | min, max |
booleen | Vrai ou faux | |
choix | Une valeur parmi options | options: [{ valeur, libelle }] |
couleur | #rrggbb | |
liste | 100 textes de 200 caractères au plus | |
cle | Clé publique hexadécimale |
Chaque réglage porte libelle, aide et defaut. Un défaut invalide fait refuser le module.
7. Outils
paisapp.outils et ctx.outils donnent les mêmes fonctions.
| Outil | Usage |
|---|---|
html, brut, echapper, adresseSure | Gabarit échappé, fragment sûr, échappement, adresse https ou locale |
markdown | Markdown réduit, rendu en fragment sûr |
montant, montantTexte | 12,50 € ; 12.50 |
date, heure, dateHeure, dateLongue, depuis | Formats de Paris |
versSecondes, versChamps | Champs date et heure vers secondes, et retour |
etapes, etape | Étapes des commandes et leurs libellés |
identifiant, geohash | Identifiant aléatoire ; geohash d'une position |
8. Essayer
Le kit d'essai charge le module comme l'application : empreinte, hôte, ports accordés. Les ports en mémoire simulent un marché complet.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { essayerModule, rendreVue, texteDe } from '#sdk/essai.js';
test('compte une livraison', async () => {
const e = await essayerModule(new URL('./fidelite.js', import.meta.url), { reglages: { palier: 2 } });
assert.equal(e.actif, true, e.raison);
const article = e.demo.articles[0];
const id = await e.simuler.recevoirCommande({ acheteur: 'c'.repeat(64), lignes: [{ article: article.adresse, quantite: 1 }] });
await e.ports.commande.etape({ commandeId: id, code: 'livree' });
const vue = await rendreVue(e, 'clients');
assert.match(texteDe(vue.html), /Clients fidèles/);
await vue.emettre('submit', { action: 'noter', champs: { note: 'Merci' } });
});
Option de essayerModule | Rôle |
|---|---|
moi | Utilisateur : propriétaire de l'entreprise de démonstration par défaut ; client ou délégué au besoin |
reglages | Valeurs des réglages |
articles, evenements, entreprises | Données du marché simulé |
delegues | Clés autorisées par le manifeste |
maintenant | Horloge de l'essai, en secondes |
sansPorts | Ports retirés, pour essayer un module privé d'un port |
outils | Outils de l'hôte à la place de ceux du socle, pour essayer le module avec ceux d'une application |
ports | Fonction qui reçoit les ports en mémoire et rend ceux qui les remplacent : un port qui se fait attendre, pour redessiner la vue pendant l'attente (ctx.rafraichir()) |
manifestes | Fonction (clé) → manifestes signés (kind 30078) publiés par cette clé ; avec elle, ctx.reglagesEntreprise existe, comme dans l'application Paisapp |
| Résultat | Rôle |
|---|---|
actif, raison, declaration | État du chargement |
ports, etat | Ports complets et état du marché : commandes, notifications, navigation, journal |
simuler | recevoirCommande, recevoirEtape, recevoirMessage, minute |
stockage | Stockage propre au module |
declencher(nom, donnees) | Lance un déclencheur et rend les résultats |
rendreVue(essai, id, { role, parametres, requete }) rend une vue dans un faux élément. emettre('click', { action, donnees }) simule un clic ; emettre('submit', { action, donnees, champs }) simule un formulaire. quitter() vérifie le nettoyage.
npm test lance tous les essais. npm run check y ajoute le contrôle des règles et du registre.
9. Publier au registre
- Déclarer le module dans
registre.config.json: catégorie, auteur, licence, relecture. Catégories : presentation, vente, organisation, automatisation, delegation. - Construire :
npm run registre. Le script charge chaque module par l'hôte, applique les règles, copie le fichier à l'octet près dansregistre/modules/<id>/<version>.jset écritregistre/index.json. - Contrôler :
npm run check. - Relire : un mainteneur relit le code, puis passe
reluà vrai. - Diffuser :
scripts/publier-registre.sh ../paisapp-fr-pro, puisscripts/publier-registre.sh ../paisapp-fr-site. paisapp.pro sert le registre ; paisapp.fr en garde une copie.
- Immutabilité : un fichier publié ne change jamais. Une modification exige une nouvelle version ; l'ancienne reste servie pour les applications qui l'épinglent.
- Remplacement :
npm run registre -- --remplacer <id>remplace une version. Il sert seulement en développement, avant toute diffusion. - Épinglage : l'atelier écrit dans le manifeste l'identifiant, la version et l'empreinte SHA-384, jamais d'adresse. L'application cherche ce triplet dans l'index du registre relu, puis prend le fichier à l'adresse du registre. Elle refuse un module absent de l'index et un fichier dont l'empreinte diffère.
- Retrait : retirer une version de l'index la bloque dans toutes les applications au chargement suivant. paisapp.fr refuse aussi tout manifeste qui la cite.
- Proposer un module : un développeur extérieur soumet son module à la relecture par
POST /api/registre/propositionssur paisapp.pro, requête signée NIP-98 par sa clé. Le corps donne le nom, la description, l'adresse du dépôt et, au choix, un contact. Depuis le dépôt paisapp-fr-pro :PAISAPP_CLE=<nsec> npm run proposer -- --nom <nom> --depot <https://…> --description <texte>. Cinq propositions par clé et par jour au plus. paisapp.pro garde la clé publique, ces champs et la date de réception ; la proposition est effacée 12 mois après sa réception.
10. Relecture
Le registre refuse un module qui contient :
- une importation statique ou dynamique,
import.metaourequire; fetch,XMLHttpRequest,WebSocket,EventSourceousendBeacon;localStorage,sessionStorage,indexedDBoudocument.cookie;evalouFunction;- une navigation directe par
locationouwindow.open; - une écriture directe de
innerHTMLhors deString(gabarit); - un attribut HTML
styleouon…dans un gabarit ; - un sélecteur de style hors de
.m-<id>,@importou@font-face.
Le relecteur vérifie ensuite le sens : ports demandés justifiés, aucune donnée envoyée hors des ports, textes échappés, messages clairs pour l'utilisateur.
11. Limites actuelles
- Automatisations : elles tournent quand l'application est ouverte. Un agent Node, toujours actif, chargera les mêmes fichiers avec ses propres adaptateurs.
- Isolement : un module tourne dans la page de l'application. La relecture, le registre comme seule source et l'empreinte épinglée le protègent ; un cloisonnement par travailleur dédié reste à venir.
- Langue : les modules officiels parlent français. Une version anglaise passera par des réglages de libellés.