monl-compiler

Un compilateur qui transforme une spécification déclarative en backend complet, déterministe et sûr.

On décrit l'intention d'une application dans un DSL dédié ; monl-compiler en génère la base de données, l'API REST, l'authentification et le contrôle d'accès — puis produit un contrat que le frontend doit respecter. La spécification est l'unique source de vérité : on ne maintient pas le code d'infrastructure à la main.

Un dialogue guidé aide à rédiger cette spécification sans connaître la syntaxe. Son mode express demande seulement le type de site, son nom et une phrase de description ; monl-compiler prépare ensuite la structure, les données de démonstration et un brief éditorial complet. Le seul recours à l'IA se situe au bout de la chaîne, pour construire le frontend à partir du contrat garanti par le compilateur — jamais pour le backend, les permissions ni la logique métier.

Sommaire

• Démarrage rapide
• Pourquoi monl-compiler ?
• Architecture
• Commandes
• La spécification
• Le backend généré
• Photos, logo et favicon
• Remplacer le contenu sans ouvrir le DSL
• Le frontend : contrat et IA spécialisée
• Qualité et vérification
• Structure du dépôt
• Documentation

Démarrage rapide

monl ouvre le dialogue guidé. Choisissez une catégorie, puis Création rapide avec l'IA : trois réponses suffisent pour produire la spécification, le backend et le contrat frontend. Cette première étape reste déterministe, sans modèle et sans appel réseau. L'IA intervient ensuite uniquement pour dessiner l'interface.

pip install .
monl
monl frontend MonProjet --provider codex
monl run MonProjet

Les fournisseurs frontend par API nécessitent l'extra optionnel : pip install '.[ai]'. Les agents locaux et monl import n'en ont pas besoin.

Yandex Cloud AI Studio est disponible par son API compatible OpenAI. La clé et le dossier restent dans l'environnement ; l'identifiant de modèle est celui affiché par AI Studio :

export YANDEX_API_KEY='…'
export YANDEX_FOLDER_ID='…'
monl frontend MonProjet --provider yandex \
  --model "gpt://$YANDEX_FOLDER_ID/yandexgpt/latest"

Si un modèle lent dépasse le délai HTTP, réduire le plafond de réponse pour cet appel : MONL_AI_MAX_TOKENS=8000 monl frontend ….

Chaque appel API mesurable ajoute dans le projet une ligne à .monl_ai_usage.jsonl (ignoré par Git) : fournisseur, modèle, durée et jetons, sans prompt, réponse ni clé. Ce journal permet de chiffrer une construction et une retouche avant de fixer le prix du service.

Le parcours Personnalisation détaillée reste disponible pour choisir chaque option, rôle, contenu éditorial et intention visuelle. Sans agent local ni clé API, ouvrez FRONTEND_PROMPT.md dans l'IA de votre choix, puis installez le ZIP ou le fichier HTML obtenu avec monl import.

Ubuntu / Debian. Le Python système est protégé (PEP 668) : préférez pipx install . à pip install . --break-system-packages.

Le parcours complet, interface comprise, est détaillé dans QUICKSTART.md.

Pourquoi monl-compiler ?

Ce que vous écrivez : une spécification d'une page. Ce que vous modifiez, ensuite : la même page. Le code produit se recompile ; il n'est jamais un point de départ à retoucher.

Ces contrôles couvrent les règles prises en charge par le compilateur ; ils ne garantissent pas la sécurité globale d'une application. La pertinence des permissions déclarées, le code custom, le frontend, les dépendances et l'exploitation demandent leurs propres vérifications. Les sources générées sont déterministes ; les secrets créés pour chaque projet et les données d'exécution ne font pas partie de cette identité. Voir le modèle de sécurité et le guide d'exploitation.

Architecture

Le dialogue produit la spécification ; le compilateur en dérive à la fois le backend et le contrat frontend ; l'IA écrit l'interface contre ce contrat ; monl run vérifie que les trois restent cohérents avant de lancer l'application.

Commandes

Plateforme web et MCP

Le compilateur peut aussi être utilisé sans cloner le dépôt sur la machine de l'utilisateur. La plateforme web explique Monl, valide une spec, compile le backend, expose son contrat et livre une archive sans secret :

monl-platform --port 8022

Les agents compatibles MCP peuvent appeler le même pipeline avec monl-mcp en stdio ou le point HTTP /mcp. Aucun second générateur n'est maintenu : CLI, web et MCP délèguent tous à compile_project.

Voir Plateforme web et serveur MCP.

En production, compose.platform.yaml lance l'application comme utilisateur non-root avec stockage persistant, readiness, quotas partagés et compilations isolées. Le port reste lié à localhost pour être publié derrière un reverse proxy HTTPS. La procédure reproductible (variables, DNS, TLS, sauvegardes et sondes) est détaillée dans le runbook de déploiement.

Chaque projet se compile dans son propre dossier via --output, afin de ne pas écraser le précédent. Les spécifications portent l'extension .ml.

La spécification

Une spec décrit des entités (tables et champs), des acteurs (rôles) et des règles d'accès. Le compilateur en dérive le schéma, les routes CRUD et le contrôle d'accès. Les identifiants sont contraints par la grammaire, ce qui exclut toute injection par les noms de tables ou de colonnes.

Le contrôle d'accès s'exprime au niveau de l'enregistrement, lecture comprise :

Les contraintes de champ sont appliquées, pas seulement déclarées :

D'autres marqueurs affinent champs et comportement : hidden, generated, categorized, derivedFrom / sumOf (montants calculés par le serveur), payable (encaissement, ci-dessous), ainsi qu'un bloc seed idempotent qui pré-remplit la base au démarrage. Une règle sans effet est refusée à la compilation plutôt qu'ignorée en silence — et une règle qui désigne un champ inexistant aussi : une contrainte à laquelle rien ne correspond laisse croire à une protection qui n'existe pas.

Cinq spécifications de référence, commentées, dans exemples/ : un fichier .ml d'une page par application — portfolio, boutique, réseau social, kanban, classement — dont monl-compiler dérive tout le reste.

Le backend généré

Comptes et rôles. POST /register n'accepte que les rôles marqués selfRegister ; tout autre est refusé (403). Les comptes privilégiés se créent avec le manage.py généré, sur la machine qui héberge la base : python3 manage.py adduser <utilisateur> <role>. La même commande gère rôle, mot de passe, liste des comptes et révocation globale des sessions.

Authentification. Registre d'utilisateurs propre à chaque application (table _monl_users, mots de passe en PBKDF2-HMAC-SHA256, sel unique par compte, comparaison à temps constant). Flux : POST /register → POST /login (jeton JWT) → POST /logout (révocation avant expiration). Le rôle et l'identité portés par le jeton proviennent du compte réel, jamais d'une déclaration du client.

Secret JWT. Généré aléatoirement à la première compilation, stocké dans .jwt_secret (jamais versionné). En production, MONL_JWT_SECRET est prioritaire et permet de livrer un projet sans secret sur le disque.

Multi-workers. Révocation de jetons et limitation de débit (5 tentatives / 60 s / IP sur /register et /login) sont persistées en base, donc partagées : uvicorn app:app --workers N n'en démultiplie pas les quotas. Derrière un reverse proxy de confiance, MONL_TRUST_PROXY=1 fait lire l'IP réelle dans X-Forwarded-For ; sans ce réglage l'en-tête est ignoré, pour empêcher toute usurpation.

Migrations. Recompiler dans le même dossier, en conservant app.db, ajoute les colonnes par ALTER TABLE ADD COLUMN sans toucher aux données. Les changements destructifs ne sont pas automatisés, à dessein — voir docs/MIGRATIONS.md.

Routes servies. /docs (Swagger, toujours disponible) · / (redirige vers /docs) · /site (l'interface, si frontend/ existe et que l'app est lancée par monl run).

Vos fichiers : photos, logo, favicon

Une image cassée ne se voit qu'à l'œil, en ligne — le pire endroit pour découvrir une faute de frappe. Les fichiers que vous fournissez se déclarent donc dans la spec, et le compilateur refuse de compiler s'ils ne sont pas là :

assets
    dir: "assets"
    logo: "logo.svg"

entity Produit
    photo: Image          # un fichier LOCAL, vérifié présent

Image désigne un fichier du projet : une URL y est refusée, parce que monl ne fait aucun appel réseau et ne pourrait rien affirmer d'une adresse distante — String reste là pour ce cas, non vérifié. Le dossier vit hors de frontend/, qui est renommé à chaque reconstruction du frontend.

Pour ne pas écrire ces chemins à la main :

monl assets add ~/photos/IMG_4821.jpg --for "Halo RS"   # → assets/halo-rs.jpg
monl assets add ~/logo.svg --logo
monl assets list                                        # présents, manquants, orphelins

La commande copie le fichier, le renomme en slug, écrit la déclaration — puis fait revalider la spec obtenue par le compilateur avant de l'enregistrer. En cas de refus, ni la spec ni le dossier ne sont modifiés. Elle ne supprime jamais un fichier : remplacer une photo signale l'ancienne comme orpheline, elle ne l'efface pas.

Remplacer le contenu sans ouvrir le DSL

Le seed de démonstration permet de voir immédiatement une interface, mais il n'est pas destiné à devenir le vrai catalogue. Un humain peut remplacer textes, prix et noms de photos avec un tableur :

monl content export MonProjet
# modifier content/Produit.csv et déposer les photos dans assets/
monl content import MonProjet
monl update MonProjet

Chaque CSV conserve l'ordre des champs et des fiches. LISEZMOI.txt explique en français les valeurs permises, les champs obligatoires, les bornes et les images attendues. Une cellule vide est omise : c'est le vrai compilateur qui décide si elle était obligatoire. Les nombres invalides, fichiers absents, chemins suspects et blocs ambigus sont refusés avant toute écriture. L'import remplace le contenu complet de l'entité ; il ne fusionne jamais silencieusement deux sources de vérité.

Le frontend : contrat et IA spécialisée

L'interface est écrite par une IA, à partir d'un contrat métier et d'une direction visuelle préparée avant le code. Chaque compilation produit :

• frontend_contract.json — description machine-lisible des routes destinées à l'interface, de l'authentification et des règles de champ, dérivée de la même spec que le backend ;
• FRONTEND_PROMPT.md — un brief prêt à confier à une IA d'interface : structure, rôles, contenu et intention déclarée, sans aucune prescription visuelle.
• DESIGN_SYSTEM.md — pattern de page, tokens de départ, anti-patterns et checklist UX déterminés depuis le contrat ; il est lu avant le HTML/CSS/JS.
• DESIGN_SPEC.md — synthèse visuelle éditable ; si l'auteur la remplace, elle devient prioritaire et Monl ne l'écrase pas.
• ASSET_MANIFEST.json — plan d'assets et marqueurs de sections. Il est d'abord planned, puis devient vérifiable après monl frontend ou monl import.

Le système de design sélectionne aussi un catalogue local de patterns Monl — hero, catalogue, éditorial, réassurance, FAQ, contact et CTA final — avec des variantes adaptées au type d'application. Ces patterns sont des structures HTML/CSS/JS autonomes, pas des composants React à installer.

L'IA écrit dans frontend/ (point d'entrée index.html), que monl run sert sur /site sans jamais toucher au backend. Plusieurs voies, mêmes garde-fous :

N'importe quelle clé fait l'affaire. Les fournisseurs au dialecte OpenAI — groq, openai, openrouter, deepseek, mistral, together, xai, ollama — sont préréglés, chacun lisant sa propre variable d'environnement. Pour un point de terminaison absent de cette liste, --provider openai-compatible avec MONL_AI_BASE_URL et MONL_AI_API_KEY. Hors voie Anthropic, --model est exigé : monl ne code aucun identifiant de modèle en dur, les catalogues changeant trop vite pour qu'une valeur figée reste vraie. La clé se lit toujours dans l'environnement, jamais en argument — le shell l'archiverait.

Garde-fous communs : extensions en liste blanche, protection contre le zip-slip, frontend autonome sans CDN, direction de design injectée avant la génération, et re-vérification systématique des routes, assets et sections obligatoires.

Sans clé API, sans carte bancaire, sans réseau

Le compilateur n'appelle jamais l'extérieur. monl compile produit app.py, schema.sql, manage.py, le contrat et le brief entièrement hors ligne : le parseur, le validateur et le générateur ne contiennent aucun appel réseau. Tout le backend — routes, base, JWT, contrôle d'accès, paiement, back-office — s'obtient sans compte chez qui que ce soit.

L'IA n'intervient qu'à l'étape frontend, et cette étape a une voie sans aucune clé :

monl compile boutique.ml --output ./Boutique   # hors ligne
# coller le contenu de Boutique/docs/FRONTEND_PROMPT.md dans n'importe quel
# assistant accessible par navigateur, récupérer le résultat…
monl import interface.zip ./Boutique           # mêmes garde-fous, même vérification
monl run ./Boutique

monl import n'est pas une porte dérobée : la source vient d'une conversation, elle est donc traitée comme une entrée non fiable — liste blanche d'extensions, refus du zip-slip, refus des CDN, index.html obligatoire, puis contrôle de cohérence et smoke test, exactement comme une réponse d'API.

Restent, selon ce que vous avez sous la main : --provider ollama pour un modèle entièrement local, les agents en ligne de commande qui s'authentifient par abonnement plutôt que par clé, et les fournisseurs au dialecte OpenAI dont plusieurs proposent un palier gratuit. monl n'en privilégie aucun et n'en revend aucun : il ne consomme aucun jeton pour son propre compte.

Ce qui est prouvé, et ce qui ne l'est pas. Le parcours hors ligne, la voie copier-coller et la voie Anthropic sont éprouvés de bout en bout contre un vrai serveur. Les préréglages codex et gemini sont écrits et couverts au niveau de la plomberie, mais n'ont pas été éprouvés contre les binaires réels — les employer, c'est essuyer les plâtres.

Avant tout lancement, monl run exécute un smoke test comportemental sur un serveur éphémère à base neuve : chaque route du contrat est éprouvée en HTTP réel et, si Node.js est présent, frontend/index.html est exécuté dans jsdom contre ce serveur. Toute exception ou tout appel hors contrat bloque le lancement (--skip-smoke pour outrepasser en connaissance de cause).

Qualité et vérification

python3 -m pytest tests/ -rs --cov=src/monl --cov-report=term-missing
python3 -m pytest tests/test_platform_*.py tests/test_oauth.py tests/test_administration.py tests/test_codes_de_secours.py -rs --cov=src/monl_platform --cov-report=term --cov-fail-under=90

ruff check src tests

python3 -m mypy src/monl/ir.py src/monl/ir_types.py src/monl/planning.py src/monl/policies.py src/monl/errors.py src/monl/generator/emitters.py --strict
vulture src/monl --min-confidence 90

monl-compiler ne dépend d'aucun modèle d'IA et ne fait aucun appel réseau : dialogue, spécification et génération du backend sont entièrement déterministes. Les blocs custom produisent des coquilles vides sûres dans sandbox_ai.py, dont la logique métier est écrite à la main — aucune génération de code n'est automatisée.

Structure du dépôt

Documentation

Licence

FSL-1.1-ALv2 — Functional Source License, avec bascule automatique vers Apache-2.0 deux ans après la publication de chaque version (LICENSE).

Vous pouvez utiliser monl-compiler librement, y compris en contexte professionnel, le modifier, le redistribuer, et vous en servir pour livrer des applications à vos clients. La seule restriction est l'usage concurrent : en faire un produit ou un service commercial qui se substitue à monl-compiler. Les applications produites à partir de vos propres spécifications vous appartiennent.

Le détail en français : LICENSE-FAQ.md.

Les rapports de bug et remarques sont bienvenus dans les issues.

monl-compiler 0.9.0-beta.9