fraza-module

fraza-module construit un paquet de l'écosystème, vérifie qu'il peut être publié et le publie. Il s'adresse à qui développe le core, un module officiel ou un module tiers, jamais à un site : la commande se lance depuis la racine du dépôt du paquet.

npx fraza-module <commande>

Sans argument, la commande affiche son aide.

Chaque dépôt portait sa propre copie de ces scripts, retouchée à la main là où les paquets diffèrent. Les copies ont dérivé. Une seule implémentation vit maintenant dans @fraza/core, sous src/tools/, et ce qui change d'un paquet à l'autre se déduit du paquet lui-même : son nom, ses exports, l'emplacement de ses icônes. Un module tiers obtient les mêmes outils en installant le core, qu'il déclare déjà en peerDependencies.

Le core lance ces commandes depuis ses sources (node ./src/tools/cli.js), puisque son dist/ n'existe pas encore au moment de son propre build. Un module les lance depuis le core installé, sous node_modules/@fraza/core/dist/tools/. @fraza/start, qui n'installe pas le core, les lance par son scripts/fraza-module.js, sur le core buildé du dépôt voisin ../core, à défaut de node_modules/@fraza/core. Rien sous dist/tools/ n'est importé par un site à l'exécution.

CommandesCopier le lien de la section

Toutes les commandes sortent en 0 en cas de succès et en 1 sur un échec, détaillé sur la sortie d'erreur.

buildCopier le lien de la section

npx fraza-module build

Les étapes s'enchaînent dans cet ordre, et la première qui échoue arrête la commande :

1. sync-version, avant la compilation pour que le littéral compilé soit le bon ;
2. tsup, celui installé dans le paquet, qui lit son tsup.config.js ;
3. notices ;
4. check-colors dist ;
5. check-bundle.

Les deux contrôles lisent dist/, où esbuild a déjà retiré les commentaires : une classe citée dans un commentaire ne produit donc pas de faux positif. tsup reste une dépendance de développement de chaque paquet, à la version qu'il choisit : le core ne le livre pas.

Le core ajoute ses propres étapes après celles-ci, dans son script build : le contrôle du catalogue de variables d'environnement, la copie de la feuille de style et des polices, la copie de docs/.

sync-versionCopier le lien de la section

npx fraza-module sync-version
npx fraza-module sync-version --check

Le module de version porte un littéral, export const MODULE_VERSION = '0.3.1', régénéré depuis package.json#version. Un littéral compilé résiste au traçage de output: 'standalone' et à la réécriture de import.meta.url par Turbopack, deux cas où une lecture de package.json à l'exécution casse. Le fichier est committé.

--check sert en prepublishOnly : il empêche de publier un module de version périmé.

noticesCopier le lien de la section

npx fraza-module notices

La commande lit npm ls --omit=dev --omit=peer --all, donc l'arbre réellement installé, et écrit l'inventaire des licences. Elle retrouve le dossier de chaque paquet comme Node le résout, dans le node_modules/ le plus proche du paquet qui l'utilise, et pas dans le chemin qu'affiche npm : npm masque par *** chaque segment en forme d'UUID, si bien qu'un clone placé sous un tel dossier, comme en intégration continue ou dans un dossier temporaire, aurait listé chaque licence en UNKNOWN. Une licence GPL, AGPL, SSPL, EUPL, CDDL, EPL, MPL, OSL ou CPAL la fait échouer. Voir Licence et propriété.

Les polices recopiées dans les sources sont distribuées avec le paquet : leur licence OFL figure sous « Code tiers intégré ». La commande les repère à leurs fichiers .woff2, .woff, .ttf ou .otf, sous src/shared/fonts/ pour le core et src/fonts/ pour un module, et reproduit le OFL.txt copié à côté d'eux : la mention de droit d'auteur et le nom réservé restent ceux de l'auteur. Un dossier de polices sans OFL.txt fait échouer la commande, parce que la licence doit accompagner chaque copie. Un paquet sans police recopiée n'a pas cette section. Les icônes sont dessinées par Fraza et n'y figurent pas. Voir Polices.

changelogCopier le lien de la section

npx fraza-module changelog

La commande régénère tout l'historique à chaque exécution et ne fait jamais échouer une publication : un commit hors convention est classé dans « Autres », un dépôt sans historique git est laissé en l'état. Le détail des bornes de version, des déductions et des pieds de commit est dans Notes de version.

Le résumé de la dernière version est fusionné dans package.json#fraza, pas substitué : une clé que le paquet déclare lui-même dans ce champ survit à la régénération.

checkCopier le lien de la section

npx fraza-module check

Valide le paquet contre le contrat de module que le core installé comprend : ce qu'un module doit respecter pour s'installer et démarrer dans un projet. Chaque règle rapporte ses écarts, et la commande les affiche tous en une fois.

La plupart des règles lisent dist/, ce qui sera publié : la commande se lance après le build. Sans dist/, elle le dit et échoue. Les modules officiels la lancent en prepublishOnly, après npm run build.

La sortie liste ensuite les sous-chemins de @fraza/core importés par dist/, imports dynamiques compris, qu'il y ait des écarts ou non :

✓ Contrat 1 : @fraza/module-blog est conforme.

Sous-chemins de @fraza/core importés (3), confrontés au core installé 0.2.0 :
  @fraza/core/api
  @fraza/core/database
  @fraza/core/features/admin

La commande ne connaît pas l'historique du core : elle confronte seulement ces sous-chemins au core installé. Le module doit fonctionner avec la dernière version du core, celle que fraza-update installe.

Sur le core et sur le starter, qui ne sont pas des modules, la commande le dit et sort en 0.

check-colorsCopier le lien de la section

npx fraza-module check-colors

Lève sur une classe de palette Tailwind, sur une couleur préfixée dark: et sur une couleur arbitraire [#…]. Un composant écrit les jetons du thème, sinon il échappe au theme.js du projet. Voir Design system.

Les exceptions justifiées, comme une palette catégorielle qui distingue des types de fichiers, sont déclarées dans src/tools/check-colors.server.js du core, par paquet et par fichier, avec leur raison. Elles vivent à un seul endroit pour tout l'écosystème : une exception reste une décision relue avec le core.

check-bundleCopier le lien de la section

npx fraza-module check-bundle

Le contrôle parcourt le graphe d'imports de dist/ depuis les points d'entrée publics, en suivant les imports @fraza/core/* jusque dans le dist/ du core installé. Il signale toute chaîne qui atteint le jeu d'icônes, le barrel shared/components ou l'éditeur de blocs, et l'affiche.

Un module a toujours un chemin léger : chaque composant s'importe par @fraza/core/shared/components/<Nom>, chaque icône par @fraza/icons/<Nom>. Le constat affiche la chaîne d'imports, du point d'entrée jusqu'au barrel, pour trouver la ligne à changer.

Un deuxième contrôle part, pour le core, de chaque sous-entrée sûre depuis un fichier 'use client', et pour un module, de son entrée ./client, que l'administration charge dans le navigateur. Il suit les imports du module jusque dans le dist/ du core. Il échoue dès que l'une d'elles atteint un fichier .server.js, un module intégré de Node ou un paquet serveur comme pg, sharp ou next/headers, et affiche la chaîne la plus courte qui y mène.

Le dernier contrôle porte sur package.json#sideEffects. Le core doit le déclarer, et la liste doit couvrir chaque fichier qui agit à l'import, c'est-à-dire qui appelle quelque chose au niveau racine, comme registerPage(…), y compris dans l'initialiseur d'une variable, un export default ou le corps d'un if, ou qui écrit sur globalThis hors de la garde d'un registre, ainsi que chaque fichier visé par un import nu. Un appel qui ne fait que calculer une valeur se marque /* @__PURE__ */. Le constat donne la ligne qui fait du fichier un fichier à effet. Les commandes de package.json#bin sont écartées. Voir Effets de bord et barrels. Un module qui ne le déclare pas est sauté, ce qui est sûr : un bundler considère alors chaque fichier comme ayant des effets, et n'en supprime aucun. Un module qui le déclare, false compris, passe le même contrôle que le core.

releaseCopier le lien de la section

npx fraza-module release
npx fraza-module release minor
npx fraza-module release 0.2.1
npx fraza-module release --dry-run
npx fraza-module release -g

Au lieu d'un niveau, un numéro exact X.Y.Z fixe la version, par exemple pour aligner le core, start et les modules sur un même numéro. Il doit être une version stable, supérieure à la version actuelle.

Publie une nouvelle version du paquet en une commande. Le seul choix qui reste au développeur est le niveau : patch par défaut, minor ou major quand il le décide. La commande calcule le numéro selon semver : depuis 0.1.14, patch donne 0.1.15, minor donne 0.2.0 et major donne 1.0.0. Voir Versionner. Les changements cassants ne décident pas du niveau : changelog les note dans les notes de version, et c'est tout. Une préversion comme 1.0.0-beta.1 est refusée : la fixer à la main.

Chaque paquet la lance par son script release, en un seul appel, pour que les arguments de npm run release -- minor arrivent à la commande.

Sans -g, la version part sur registry.fraza.ca seulement : c'est le mode des versions qui servent à tester un changement dans un projet. Avec -g, un paquet @fraza/* part aussi sur npmjs, d'où les sites installent. Un module @fraza-pro/* ne va jamais sur npmjs : -g ne change rien pour lui, et la commande le dit.

Les étapes s'enchaînent dans cet ordre, et la première qui échoue arrête la commande :

1. Vérifications, avant toute écriture. Le paquet est dans un dépôt git, sur une branche qui suit une branche distante, affichée en tête. La commande lance git fetch sur le dépôt distant de cette branche et refuse une branche en retard sur lui : sans cela, la publication partirait et seul git push, à la fin, serait refusé. Sans réseau, elle s'arrête là. Aucune publication précédente n'est restée arrêtée après son commit de version. L'arbre de travail est propre, l'étiquette v<nouvelle version> n'existe ni en local ni sur le dépôt distant, CHANGELOG.md et changelog.json sont déclarés dans files, et publishConfig est conforme (voir publish). Puis la commande installe la dernière version publiée de chaque dépendance Fraza du paquet (npm install --no-save @fraza/…@latest, sans toucher à package.json ni au lockfile). Le registre suit la publication, jamais ~/.npmrc : registry.fraza.ca par défaut, qui porte les dernières versions de test, npmjs avec -g, pour vérifier le paquet contre les versions qu'un site recevra avec lui. Elle lance ensuite npm run build, check pour un module, npm test quand le paquet déclare ce script, et l'arbre doit être resté propre après le build. Un échec ici laisse le dépôt exactement dans son état d'avant.
2. Montée de version. La commande affiche ancienne → nouvelle, écrit la version dans package.json et dans les entrées racine de package-lock.json, régénère le module de version (sync-version) et les notes de version (changelog), relance npm run build, puis committe ces fichiers seuls avec le message chore: bump version to X.Y.Z. THIRD-PARTY-NOTICES.md, que le build régénère d'après les paquets installés, part dans ce même commit : il change quand une dépendance Fraza vient d'avancer. Un échec avant le commit remet ces fichiers dans leur état d'avant.
3. Publication sur chaque registre, par publish : prepublishOnly relance le build et les contrôles du paquet, puis le même tarball part vers registry.fraza.ca, précédé de npmjs avec -g pour un paquet @fraza/*.
4. Étiquette et envoi, seulement si chaque registre a accepté la version. git tag -a v<version> -m v<version>, puis git push --atomic --follow-tags, qui envoie la branche et l'étiquette ensemble ou aucune des deux.

Le lockfile est modifié comme un fichier JSON, pas par npm install : un module se construit souvent contre un core installé avec --no-save, qu'une installation inscrirait dans son lockfile.

Un échec après le commit ne s'annule pas en silence. La commande s'arrête et dit où en est la publication : commit de version fait en local, aucune étiquette, rien de poussé quand un registre a refusé la version, et la liste des registres qui l'ont et de ceux où elle manque. Elle affiche les commandes pour reprendre (npm run release:publish, avec -g si la publication visait npmjs, qui ne publie que là où la version manque, puis l'étiquette et l'envoi), et git reset --hard HEAD~1 pour annuler la montée de version tant qu'aucun registre ne l'a reçue. Quand seul l'envoi échoue, elle dit si l'étiquette a atteint le dépôt distant, et propose git pull --no-rebase avant de pousser à nouveau : un rebase réécrirait le commit de version, que l'étiquette publiée désigne. Relancer npm run release à ce stade monterait la version une deuxième fois : la commande refuse de partir quand HEAD est le commit de version de la version courante, pas encore sur le dépôt distant, et redonne les commandes pour reprendre ou annuler.

npm run release --dry-run, sans --, donne l'option à npm et non au script. La commande le détecte et simule aussi : sans cela, npm publish ne ferait que simuler alors que l'étiquette et l'envoi auraient lieu.

npm run release -g donne de même -g à npm, qui le transmet au script comme npm_config_global. La commande le lit comme une demande de publication sur npmjs, puis le retire de son environnement : chaque npm qu'elle lance en hériterait, et npm install --no-save installerait en global.

publishCopier le lien de la section

npx fraza-module publish
npx fraza-module publish --dry-run
npx fraza-module publish -g

Publie la version actuelle de package.json, sans la monter, sur chaque registre du paquet où elle manque. release l'appelle à son étape 3. Chaque paquet Fraza l'expose aussi par son script release:publish, pour terminer une publication interrompue. Le core et @fraza/start n'installent pas fraza-module comme dépendance : npm run release:publish y lance le CLI du dépôt.

Avec -g, npmjs passe en premier : c'est le registre d'où les sites installent, et le plus strict, puisqu'un numéro de version n'y est jamais réutilisable. Un refus de npmjs arrête la publication avant que le secours ne reçoive une version que npmjs n'a pas.

Les étapes :

1. Contrôle de publishConfig. Un paquet @fraza/* déclare "access": "public" et aucun registry : npmjs refuse un paquet de scope en restricted sans abonnement, et un npm publish lancé à la main part ainsi vers npmjs, en public. Un module @fraza-pro/* déclare "registry": "https://registry.fraza.ca/" : sans cette ligne, un npm publish lancé à la main enverrait un module payant sur npmjs. release et release-check font le même contrôle.
2. Ce que chaque registre a déjà. npm view <nom>@<version> sur chaque registre. Un paquet inconnu compte comme une version absente. Toute autre erreur arrête la commande : publier à l'aveugle pourrait viser une version qui existe déjà.
3. Un seul tarball. Si un registre a déjà la version, npm pack <nom>@<version> télécharge son tarball. Sinon, la commande lance npm run prepublishOnly (ou build sans ce script), puis npm pack dans le paquet. Un tarball se publie sans scripts de cycle de vie : les contrôles de prepublishOnly passent donc ici, une seule fois.
4. npm publish <tarball> vers chaque registre où la version manque.

Les deux registres reçoivent ainsi le même fichier, octet pour octet. Le package-lock.json d'un site vérifie l'empreinte de chaque tarball : c'est ce qui permet à un site de basculer sur le registre de secours sans toucher à son lockfile autrement que pour l'hôte.

Le registre est passé par scope, --@fraza:registry=<adresse>, jamais par --registry : npm choisit une ligne de scope de ~/.npmrc avant --registry, et la machine d'un mainteneur pointe souvent @fraza vers registry.fraza.ca. Les options de ligne de commande passent avant publishConfig.

La commande se relance sans risque : un registre qui a déjà la version est sauté. C'est aussi ainsi qu'une version publiée sur registry.fraza.ca seulement est portée sur npmjs, avec -g : son tarball est téléchargé et envoyé tel quel.

npm peut demander un code à usage unique quand le compte npmjs a la double authentification : la sortie de npm s'affiche telle quelle et le code se saisit dans le terminal.

Dépendances FrazaCopier le lien de la section

La dernière version de chaque paquet Fraza fonctionne avec les autres. Personne ne suit quelle version va avec quelle autre : les paquets Fraza se déclarent entre eux avec "*" (@fraza/icons dans le core, @fraza/core dans les peerDependencies d'un module), et la commande n'écrit aucune plage. Elle construit et teste le paquet contre la dernière version de chacun, quelle que soit celle du lockfile. Un site reçoit la dernière version exacte de chacun par fraza-update.

release-checkCopier le lien de la section

npx fraza-module release-check

Répond à une seule question : npm publish peut-il partir maintenant ? La commande ne monte aucune version, ne committe rien, ne crée aucune étiquette et ne publie rien. Elle sert pour une version déjà montée et committée à la main : release fait ses propres vérifications.

1. L'arbre de travail git est propre, et l'étiquette v<version> n'existe pas encore.
2. sync-version --check passe.
3. CHANGELOG.md et changelog.json existent, sont déclarés dans files, et changelog.json s'ouvre sur la version de package.json. package.json#fraza porte le résumé que lit fraza-update. publishConfig est conforme au scope du paquet : voir publish.
4. npm run build passe.
5. Pour un module, check passe, sur le dist/ que le build vient d'écrire.
6. npm test passe, quand le paquet déclare ce script.
7. L'arbre de travail est toujours propre : un fichier suivi que le build régénère, comme le module de version ou THIRD-PARTY-NOTICES.md, était périmé dans le commit.

Les étapes 1 à 3 sont vérifiées ensemble, et le build ne part que si elles passent. La procédure complète de publication est dans Publication.

test-cleanCopier le lien de la section

npx fraza-module test-clean --dry-run
npx fraza-module test-clean --older-than 6
npx fraza-module test-clean

Liste les schémas de test restés sur la base de FRAZA_TEST_DATABASE_URL, avec leur âge lu dans leur nom, puis les supprime. Un processus de test tué par SIGKILL en laisse un : voir Tests.

Sans --older-than, la commande supprime tous les schémas de test du préfixe, y compris ceux d'une suite en cours : la lancer quand aucun test ne tourne. Seul un nom au format de l'aide aux tests est touché. La commande lit la variable dans l'environnement du terminal, jamais dans un fichier .env, comme l'aide aux tests. Elle sort en 1 si la variable manque, si la base ne répond pas, ou si un schéma n'a pas pu être supprimé.

Preset tsupCopier le lien de la section

Le core exporte la configuration tsup commune, defineFrazaConfig, sous @fraza/core/tools/tsup. Le tsup.config.js d'un module tient en trois lignes :

import { defineFrazaConfig } from '@fraza/core/tools/tsup';

export default defineFrazaConfig();

Le preset compile chaque fichier .js et .jsx du dossier en module autonome, bundle: false, JSX transformé par react/jsx-runtime, outbase sur le dossier des sources. Les fichiers *.test.js sont exclus : un test compilé dans dist/ partirait dans chaque projet. Les raisons de bundle: false sont dans Build et exports.

Le fichier n'importe pas tsup : une configuration tsup est un objet, et tsup reste ainsi une dépendance de développement du paquet. Le core construit lui-même avec ce preset, importé depuis ses sources.

NotesCopier le lien de la section

fraza-module n'est pas fraza-modules. Le second, au pluriel, régénère les manifestes de modules d'un site. Le premier construit un paquet.

La commande travaille sur le paquet du dossier courant, trouvé en remontant jusqu'au premier package.json. Dans un script npm, c'est la racine du paquet. test-clean fait exception : il travaille sur la base de test.

Un module qui utilise fraza-module dépend de la version du core qui l'a introduite. La commande vient du core installé dans node_modules : un core plus ancien ne la fournit pas.