@mostajs/wagon-engine 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — @mostajs/wagon-engine
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+Format : Keep a Changelog ; versions : SemVer.
+
+## [0.1.0] — 2026-10-26
+
+### Extrait
+- Le gabarit `Entreprise/mosta-wagon` 0.11.0 devient un module, sur décision du fondateur (26/10, `saas-making/methode/IDEES-A-INSTRUIRE.md` §I-2). Trois copies identiques de `src/wagon.mjs` existaient, et la 0.11 n'avait atteint que l'une d'elles.
+- `creerWagon`, `schemasWagon`, `sauvegarder` et `suivrePalette` sont repris sans changement de comportement.
+- La suite de conformité (T-WAG-1 à 29) est **publiée**. Elle juge la greffe de `WAGON_GREFFE`, ou du dossier courant.
+
+### Ajouté
+- `demarrer({ config, charge, racine })` fait tout le démarrage d'une greffe : ce que faisait chaque `server.mjs` copié.
+- Les commutateurs `PAIEMENT_STRIPE`, `PAIEMENT_CHARGILY`, `PAIEMENT_SATIM` et `PAIEMENT_PAYPAL` coupent un moyen de paiement par le `.env`, comme dans RestoTrax. L'utilisateur choisit parmi les moyens actifs.
+
+### Changé
+- Le dossier légal par défaut est celui de la greffe (`racine/legal`).
+- Dépendances à jour : `wagon-ui` ^0.9.1, `markdown-html` ^0.3.0, `garde-http` ^0.2.0, `payment` ^2.6.0, `subscriptions-plan` ^0.9.0 (SATIM).

package/LICENSE

@@ -0,0 +1,15 @@
+@mostajs/wagon-engine
+Copyright (C) 2026 Dr Hamid MADANI <drmdh@msn.com>
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/agpl-3.0.html>.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @mostajs/wagon-engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later · Node ≥ 20
+
+**Le wagon d'un SaaS, une fois pour toutes.** Il fournit les comptes, la connexion (mot de passe ou code par courriel), les paliers et leurs quotas, le paiement (Stripe, Chargily, SATIM, PayPal), l'espace client, l'administration, les pages légales, le référencement, les sauvegardes, et trois langues (fr, en, ar).
+
+Une **greffe** n'apporte que ce qu'elle vend :
+
+| la greffe écrit | rôle |
+|---|---|
+| `wagon.config.mjs` | identité, couleurs, langues, paliers et prix, moyens de paiement proposés |
+| `charge/index.mjs` | ses pages et son API (`routes`), ses ressources mesurées, son accueil |
+| `legal/*.md` | ses textes légaux, avec des jetons `{{…}}` remplis par la configuration |
+| `.env` | ses secrets et ses adresses |
+
+## Installer
+
+```bash
+npm install @mostajs/wagon-engine
+```
+
+## Démarrer une greffe
+
+```js
+// server.mjs
+import { demarrer } from '@mostajs/wagon-engine';
+import config from './wagon.config.mjs';
+import charge from './charge/index.mjs';
+await demarrer({ config, charge });
+```
+
+`demarrer` lit `.env` dans le dossier courant (`@mostajs/config`, cascade `MOSTA_ENV`), monte le courriel, la base et les moyens de paiement actifs, puis écoute sur `PORT`.
+
+| `.env` | rôle |
+|---|---|
+| `PORT`, `HOST` | écoute (4800, 127.0.0.1) |
+| `WAGON_BASE_URL` | l'adresse publique (liens des courriels, retours de paiement) |
+| `WAGON_DB_DIALECT`, `WAGON_SGBD` | la base : `sqlite` et un chemin, ou `postgres` et `postgresql://…` |
+| `WAGON_EMAIL_SERVER_HOST`, `…_PORT`, `…_USER`, `…_PASSWORD`, `WAGON_EMAIL_FROM` | le courriel (SMTP) |
+| `WAGON_STRIPE_SECRET_KEY`, `WAGON_STRIPE_WEBHOOK_SECRET` | Stripe |
+| `CHARGILY_SECRET_KEY` · `SATIM_MERCHANT_ID`, `SATIM_PASSWORD`, `SATIM_TERMINAL_ID` · `PAYPAL_…` | les banques prépayées proposées par `config.paiement.prepaye` |
+| `PAIEMENT_STRIPE=off`, `PAIEMENT_CHARGILY=off`, `PAIEMENT_SATIM=off`, `PAIEMENT_PAYPAL=off` | **coupe un moyen** sans toucher à ses clés |
+| `WAGON_ADMINS` | les courriels administrateurs (confirmés par un code reçu) |
+
+**Le paiement est au choix de l'utilisateur**, parmi les moyens actifs. Un moyen est actif quand ses clés sont dans le `.env` et que son commutateur n'est pas sur `off`. Une banque prépayée doit en plus être proposée par la configuration.
+
+## Juger une greffe
+
+La suite de conformité est publiée avec le moteur. Elle juge la greffe du dossier courant, ou celle que désigne `WAGON_GREFFE` :
+
+```bash
+npx mjs-unit node_modules/@mostajs/wagon-engine/src/conformite/conformite.test.mjs
+```
+
+Elle contrôle les comptes, le quota, le paiement (signatures Stripe réelles, banques simulées), la sécurité (CSRF, en-têtes, cookie), l'administration, les pages légales, la sauvegarde et les permissions par page. Un essai sans objet pour une greffe est **ignoré avec son motif**, jamais compté réussi.
+
+## Vérifier
+
+```bash
+node examples/verifier.mjs   # une greffe de vingt lignes démarre : paiement, paliers, texte légal, quota
+```
+
+## Référence
+
+L'API et le contrat complet de la charge sont dans `llms.txt`.

package/examples/verifier.mjs

@@ -0,0 +1,62 @@
+// @mostajs/wagon-engine — exemple de vérification (DEVRULES §12) : une greffe minimale démarre sur le moteur.
+// Author: Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+// Lancer : node examples/verifier.mjs   (sort en erreur si une réponse n'est pas celle attendue)
+//
+// La greffe tient en trois choses : une configuration, une charge, et un .env. Elle n'écrit ni route de compte, ni
+// paiement, ni page légale : le moteur les apporte. Ici, dans un dossier jetable, avec une base sqlite.
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { demarrer } from '../src/index.js';
+
+const racine = mkdtempSync(join(tmpdir(), 'greffe-'));
+mkdirSync(join(racine, 'legal'));
+writeFileSync(join(racine, 'legal', 'cgu.fr.md'), '# Conditions\n\n{{SERVICE}} est édité par Exemple SARL.\n');
+writeFileSync(join(racine, '.env'), `PORT=0\nWAGON_SGBD=${join(racine, 'wagon.db')}\nWAGON_BASE_URL=http://127.0.0.1\nCHARGILY_SECRET_KEY=test_sk_exemple\nPAIEMENT_STRIPE=off\n`);
+
+const config = {
+  marque: { nom: 'Échos', symbole: 'É', auteur: 'Exemple SARL' }, langues: ['fr', 'en', 'ar'], connexion: 'motdepasse',
+  paiement: { prepaye: { chargily: 'DZD' } }, legal: { EDITEUR_NOM: 'Exemple SARL' },
+  paliers: [
+    // Le visiteur sans compte : son palier, hors vente. Sans lui, la charge lui est « non comprise » (403).
+    { slug: 'anonyme', name: 'Anonyme', price: 0, active: false, sortOrder: -1, limits: { echosParJour: 3, maxCles: 0 } },
+    { slug: 'gratuit', name: 'Gratuit', price: 0, sortOrder: 0, limits: { echosParJour: 5, maxCles: 1 } },
+    { slug: 'pro', name: 'Pro', price: 900, sortOrder: 1, limits: { echosParJour: 500, maxCles: 3 }, prepaid: { DZD: { month: 150000, year: 1500000 } } },
+  ],
+};
+// La charge : ce que le produit vend. Ici, répéter un texte, compté par jour.
+const charge = {
+  liens: [{ href: '/echo', libelle: { fr: 'Écho', en: 'Echo', ar: 'صدى' } }],
+  ressources: [{ cle: 'echo', limite: 'echosParJour', periode: 'jour', libelle: { fr: 'Échos', en: 'Echoes', ar: 'أصداء' },
+    parPeriode: { fr: '{n} échos par jour', en: '{n} echoes a day', ar: '{n} صدى في اليوم' } }],
+  async routes(req, res, ctx) {
+    if (ctx.chemin !== '/echo') return false;
+    const v = await ctx.consommer('echo');
+    if (!v.allowed) return ctx.refuser(v);
+    return ctx.json(200, { echo: new URL(req.url, 'http://x').searchParams.get('t') ?? '' });
+  },
+};
+
+const g = await demarrer({ config, charge, racine, journal: { log: (m) => console.log(`   ${m}`), warn() {}, error() {} } });
+const base = `http://127.0.0.1:${g.serveur.address().port}`;
+try {
+  console.log(`1. greffe démarrée ; moyens de paiement actifs : ${g.moyens.join(', ')} (Stripe coupé par PAIEMENT_STRIPE=off)`);
+  assert.deepEqual(g.moyens, ['chargily']);
+  const sante = await (await fetch(`${base}/health`)).json();
+  assert.equal(sante.ok, true);
+  console.log('2. /health :', JSON.stringify({ ok: sante.ok, application: sante.application }));
+  const tarifs = await (await fetch(`${base}/tarifs`)).text();
+  assert.ok(tarifs.includes('Pro') && tarifs.includes('Gratuit'));
+  console.log('3. /tarifs : les paliers de la configuration sont affichés');
+  const cgu = await (await fetch(`${base}/cgu`)).text();
+  assert.ok(cgu.includes('Exemple SARL'));
+  console.log('4. /cgu : le texte légal de LA GREFFE, ses jetons remplis');
+  const e = await (await fetch(`${base}/echo?t=bonjour`)).json();
+  assert.equal(e.echo, 'bonjour');
+  console.log('5. /echo : la charge répond à un visiteur, son quota (palier anonyme, 3 par jour) est compté par le moteur');
+  console.log('✓ vérification réussie');
+} finally {
+  await g.fermer();
+  rmSync(racine, { recursive: true, force: true });
+}

package/llms.txt

@@ -0,0 +1,40 @@
+# @mostajs/wagon-engine — fiche LLM
+
+> Le wagon d'un SaaS, une fois pour toutes : comptes, connexion, paliers, quotas, paiement (Stripe, Chargily, SATIM,
+> PayPal), espace client, administration, pages légales, robots/sitemap, sauvegarde, fr/en/ar. Une GREFFE n'apporte que
+> wagon.config.mjs, charge/, legal/ et son .env. N2 (pack). Extrait du gabarit mosta-wagon 0.11.0 le 26/10/2026.
+
+- Version: 0.1.0 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Chemin: mostajs/mosta-platform-stack/mosta-wagon-engine · gabarit d'une greffe : Entreprise/mosta-wagon
+
+## EXPORTS
+- demarrer({ config, charge, racine = cwd, journal }) → { wagon, serveur, moyens: string[], fermer() }
+- creerWagon({ config, charge, sgbd: string|{dialect,uri}, baseUrl, stripe?, webhookSecret?, transport?, journal?,
+  paiement?: { banques: { chargily:'DZD', … }, port? }, racine? }) → { handler, catalogue(), catalogueStripe(), fermer(), … }
+- schemasWagon() (sauvegarde) · sauvegarder({ cibles, driver, seau, recipients, garder }) · suivrePalette(…)
+- '@mostajs/wagon-engine/conformite' = src/conformite/conformite.test.mjs (suite mjs-unit, juge WAGON_GREFFE ou cwd)
+
+## .env lu par demarrer
+PORT, HOST · WAGON_BASE_URL · WAGON_DB_DIALECT (sqlite|postgres…), WAGON_SGBD · WAGON_EMAIL_SERVER_HOST/PORT/USER/PASSWORD,
+WAGON_EMAIL_FROM (ou WAGON_COURRIEL_FICHIER pour les essais) · WAGON_STRIPE_SECRET_KEY|RESTRICTED_KEY, WAGON_STRIPE_WEBHOOK_SECRET ·
+CHARGILY_SECRET_KEY|API_KEY · SATIM_MERCHANT_ID, SATIM_PASSWORD, SATIM_TERMINAL_ID · PAYPAL_CLIENT_ID, PAYPAL_SECRET,
+PAYPAL_WEBHOOK_ID · PAIEMENT_<STRIPE|CHARGILY|SATIM|PAYPAL>=off (coupe le moyen) · WAGON_ADMINS · WAGON_INDEXER.
+Moyen ACTIF = clés présentes ET commutateur ≠ off (ET, pour une banque prépayée, proposée par config.paiement.prepaye).
+
+## CONTRAT DE LA CHARGE (charge/index.mjs)
+liens · ressources (quota { cle, limite, periode } | plafond { cle, limite, plafond: true }) · accueil · textes ·
+routes(req, res, ctx) (passent en premier ; true si servie) · conformite (essai de quota T-WAG-3) · amorcer() (base au
+démarrage) · exporterCompte(id), effacerCompte(id) (RGPD) · sitemap() · sauvegarde() · permissions (0.11 :
+{ '/page': { microphone: 'self' }, '/dossier/*': … }, garde-http ≥ 0.2).
+ctx : chemin, methode, lang, t, ui, page({ titre, contenu }), envoyer, json, rediriger, formulaire, corpsJson({ strict }),
+compte, consommer(cle), refuser(v), palier(), plafond(cle, n), admin.
+
+## PIÈGES
+- wagon-ui ≥ 0.9 exige config.marque.auteur.
+- Sans palier « anonyme » (config.planAnonyme), un visiteur sans compte n'a droit à aucune ressource (403).
+- loadEnv ne SURCHARGE pas une variable déjà dans l'environnement (l'env réel prime sur le .env).
+- Base PostgreSQL : la greffe ajoute la dépendance « pg ».
+
+## NE FAIT PAS
+ce que le produit vend (la charge) · les pages (@mostajs/wagon-ui) · comptes et clés (@mostajs/comptes) · encaisser,
+compter (@mostajs/payment, @mostajs/subscriptions-plan) · en-têtes (@mostajs/garde-http).

package/package.json

@@ -1,6 +1,109 @@
 {
   "name": "@mostajs/wagon-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Le wagon d'un SaaS, une fois pour toutes : comptes, connexion, paliers, quotas, paiement (Stripe, Chargily, SATIM), espace client, administration, pages légales, fr/en/ar. Une greffe n'apporte que wagon.config.mjs, charge/, legal/ et son .env ; la suite de conformité publiée juge la greffe.",
+  "keywords": [
+    "mostajs",
+    "saas",
+    "wagon",
+    "boilerplate",
+    "subscriptions",
+    "auth",
+    "payment",
+    "chargily"
+  ],
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./conformite": "./src/conformite/conformite.test.mjs",
+    "./sauvegarde": "./src/sauvegarde.mjs"
+  },
+  "files": [
+    "src",
+    "examples",
+    "llms.txt",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "bash test-scripts/run-tests.sh"
+  },
+  "dependencies": {
+    "@mostajs/auth-lite": "^1.2.0",
+    "@mostajs/auth-plug": "^0.3.0",
+    "@mostajs/auth-ui": "^0.4.0",
+    "@mostajs/backup": "^0.5.0",
+    "@mostajs/blob-store": "^0.4.1",
+    "@mostajs/comptes": "^0.1.0",
+    "@mostajs/config": "^1.1.0",
+    "@mostajs/crypto-box": "^0.3.0",
+    "@mostajs/data-plug": "^1.2.6",
+    "@mostajs/garde-http": "^0.2.0",
+    "@mostajs/i18n": "^0.2.0",
+    "@mostajs/mailer": "^0.2.0",
+    "@mostajs/markdown-html": "^0.3.0",
+    "@mostajs/orm": "^2.12.1",
+    "@mostajs/payment": "^2.6.0",
+    "@mostajs/subscriptions-plan": "^0.9.0",
+    "@mostajs/wagon-ui": "^0.9.1",
+    "better-sqlite3": "^12.11.1",
+    "stripe": "^17.7.0"
+  },
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.10.0"
+  },
+  "mostajs": {
+    "niveau": "N2",
+    "nature": "compose",
+    "reutilisabilite": "multi-domaine",
+    "depend_de": [
+      "@mostajs/auth-lite",
+      "@mostajs/auth-plug",
+      "@mostajs/auth-ui",
+      "@mostajs/backup",
+      "@mostajs/blob-store",
+      "@mostajs/comptes",
+      "@mostajs/config",
+      "@mostajs/crypto-box",
+      "@mostajs/data-plug",
+      "@mostajs/garde-http",
+      "@mostajs/i18n",
+      "@mostajs/mailer",
+      "@mostajs/markdown-html",
+      "@mostajs/orm",
+      "@mostajs/payment",
+      "@mostajs/subscriptions-plan",
+      "@mostajs/wagon-ui"
+    ],
+    "forme": "pack",
+    "question": "Comment transporter le service qu'on vend — comptes, connexion, paliers, paiement, pages légales, administration — sans le recoder à chaque produit ?",
+    "entites": [],
+    "verbes": [
+      "creerWagon",
+      "demarrer",
+      "schemasWagon",
+      "sauvegarder",
+      "suivrePalette"
+    ],
+    "interop": [
+      "Stripe Checkout & webhooks",
+      "Chargily Pay v2",
+      "SATIM (CIB, Edahabia)",
+      "Fetch Metadata / CSP (garde-http)"
+    ],
+    "ne_fait_pas": {
+      "ce que le produit vend": "la charge de chaque greffe (charge/)",
+      "les pages": "@mostajs/wagon-ui",
+      "les comptes et clés": "@mostajs/comptes",
+      "encaisser, compter un quota": "@mostajs/subscriptions-plan, @mostajs/payment",
+      "les en-têtes de sécurité": "@mostajs/garde-http"
+    }
+  }
+}