@fraza/start 0.0.0-stage → 0.3.5

package/bin/project.js

@@ -0,0 +1,281 @@
+// Étapes de génération d'un projet Fraza, sans effet de bord à l'import.
+//
+// `cli.js` les enchaîne ; les tests de `test/` les appellent une par une sur un
+// dossier temporaire. Chaque fonction reçoit les chemins qu'elle touche : aucune
+// ne lit le dossier courant d'elle-même.
+
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const REGISTRY_HOST = 'registry.fraza.ca';
+export const REGISTRY_URL = `https://${REGISTRY_HOST}/`;
+
+/** Plancher de Node, le même que `engines.node` et que le core. */
+export const MIN_NODE = [20, 12];
+
+// Version de `create-next-app`, donc de Next, installée dans le projet généré.
+// C'est le dernier correctif de la version mineure contre laquelle le core a
+// été validé (`packages.next.tested` de son `supported.json`) : un correctif de
+// Next ne change pas d'API, et il porte souvent une faille corrigée : 16.3.5,
+// validée d'abord, est touchée par GHSA-vcvr-r3jv-pc5j, corrigée en 16.3.8,
+// la version que le core déclare maintenant.
+// `npm run check:contract` échoue si l'épingle quitte la version mineure
+// validée ou passe sous la version validée (`pinFollowsTestedNext`).
+export const CREATE_NEXT_APP_VERSION = '16.3.8';
+
+// Entrées tolérées dans le dossier cible : métadonnées d'éditeur ou de gestion
+// de versions, que ni `create-next-app` ni ce CLI n'écrivent. Toute autre entrée
+// ferait écraser un fichier existant, ou échouer `create-next-app` après coup.
+const ALLOWED_ENTRIES = new Set([
+	'.claude',
+	'.cursor',
+	'.DS_Store',
+	'.git',
+	'.gitattributes',
+	'.hg',
+	'.idea',
+	'.vscode',
+	'.zed',
+	'LICENSE',
+	'Thumbs.db',
+]);
+
+// `create-next-app` écrit un AGENTS.md, et `next dev` le réécrit à chaque
+// démarrage. Il ne remplace que ce qui se trouve entre ses propres marqueurs et
+// laisse le reste du fichier intact : notre bloc, posé à la suite avec ses
+// marqueurs à lui, survit donc aux régénérations. On le délimite pareillement
+// pour pouvoir le mettre à jour sans le dupliquer.
+export const AGENTS_BLOCK_START = '<!-- BEGIN:fraza-agent-rules -->';
+export const AGENTS_BLOCK_END = '<!-- END:fraza-agent-rules -->';
+
+/**
+ * Compare la version de Node au plancher.
+ * @param {string} version Par exemple `process.versions.node`.
+ * @returns {boolean}
+ */
+export function isSupportedNode(version) {
+	const [major, minor] = String(version).split('.').map(Number);
+	if (major !== MIN_NODE[0]) return major > MIN_NODE[0];
+	return minor >= MIN_NODE[1];
+}
+
+/**
+ * Dit si l'épingle de `create-next-app` suit la version de Next validée par le
+ * core : même version majeure et mineure, et pas en dessous.
+ * @param {string} pin
+ * @param {string} tested
+ * @returns {boolean}
+ */
+export function pinFollowsTestedNext(pin, tested) {
+	const [pinMajor, pinMinor, pinPatch] = String(pin).split('.').map(Number);
+	const [major, minor, patch] = String(tested).split('.').map(Number);
+	return pinMajor === major && pinMinor === minor && pinPatch >= patch;
+}
+
+/**
+ * Liste les entrées du dossier qui empêchent d'y générer un projet.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function findConflictingEntries(dir) {
+	return fs.readdirSync(dir).filter((name) => !ALLOWED_ENTRIES.has(name)).sort();
+}
+
+/**
+ * Ajoute, ou remplace, le bloc Fraza dans l'AGENTS.md du projet généré. Un agent
+ * qui ouvre le dépôt apprend ainsi d'où vient le code et où lire la doc livrée
+ * dans `node_modules/@fraza/core/dist/docs/`.
+ * @param {string} agentsPath
+ * @param {string} block
+ */
+export function writeAgentsBlock(agentsPath, block) {
+	if (!fs.existsSync(agentsPath)) {
+		fs.writeFileSync(agentsPath, `${block}\n`);
+		return;
+	}
+
+	const existing = fs.readFileSync(agentsPath, 'utf-8');
+	const start = existing.indexOf(AGENTS_BLOCK_START);
+	const end = existing.indexOf(AGENTS_BLOCK_END, start);
+
+	if (start !== -1 && end !== -1) {
+		const before = existing.slice(0, start);
+		const after = existing.slice(end + AGENTS_BLOCK_END.length);
+		fs.writeFileSync(agentsPath, before + block + after);
+		return;
+	}
+
+	const separator = existing.length === 0 || existing.endsWith('\n') ? '\n' : '\n\n';
+	fs.writeFileSync(agentsPath, `${existing}${separator}${block}\n`);
+}
+
+/**
+ * Masque l'indicateur de développement de Next dans le `next.config.mjs` écrit
+ * par `create-next-app`. Le fichier est complété, jamais remplacé : avec
+ * Turbopack, `create-next-app` peut y brancher Tailwind (règle `turbopack.rules`
+ * vers `@tailwindcss/turbopack`, sans `postcss.config.mjs`). Un gabarit qui
+ * l'écraserait laisserait alors le projet sans aucun style.
+ * @param {string} configPath
+ * @returns {boolean} `false` si le fichier manque ou n'a pas la forme attendue.
+ */
+export function hideDevIndicators(configPath) {
+	if (!fs.existsSync(configPath)) return false;
+
+	const existing = fs.readFileSync(configPath, 'utf-8');
+	if (existing.includes('devIndicators')) return true;
+
+	const pattern = /(const nextConfig = \{\n)/;
+	if (!pattern.test(existing)) return false;
+
+	fs.writeFileSync(configPath, existing.replace(pattern, '$1  devIndicators: false,\n'));
+	return true;
+}
+
+/**
+ * Complète le `package.json` écrit par `create-next-app` : `fraza-modules sync`
+ * avant `next dev` et `next build`, et à chaque installation.
+ * @param {object} pkg
+ * @param {Record<string, string>} siteOverrides
+ * @returns {object} Un nouvel objet, `pkg` n'est pas modifié.
+ */
+export function withFrazaScripts(pkg, siteOverrides = {}) {
+	const next = { ...pkg, scripts: { ...pkg.scripts } };
+	next.scripts.postinstall = 'fraza-modules sync';
+	next.scripts.dev = 'fraza-modules sync && next dev';
+	next.scripts.build = 'fraza-modules sync && next build';
+	next.scripts.audit = 'npm audit --omit=dev';
+
+	const overrides = { ...siteOverrides, ...pkg.overrides };
+	if (Object.keys(overrides).length > 0) next.overrides = overrides;
+	return next;
+}
+
+/**
+ * Ajoute au `.gitignore` de `create-next-app` les deux règles de Fraza.
+ *
+ * Les règles `.env*` de `create-next-app` restent actives : les valeurs d'une
+ * machine (`.env.local`) et les secrets ne sont jamais suivis. Seul le modèle
+ * `.env.example`, sans aucune valeur secrète, est rendu à git. Le `.npmrc` n'est
+ * pas ignoré : il ne porte que les scopes du registre, dont la machine de build
+ * a besoin pour installer `@fraza/core`.
+ * @param {string} gitignore
+ * @returns {string}
+ */
+export function withFrazaGitignore(gitignore) {
+	let next = gitignore === '' || gitignore.endsWith('\n') ? gitignore : `${gitignore}\n`;
+	const add = (lines) => {
+		next += `\n${lines.join('\n')}\n`;
+	};
+
+	// La négation n'agit que placée après la règle qui ignore : sans `.env*`
+	// plus haut, elle ne protégerait rien.
+	if (!/^\.env\*$/m.test(next)) {
+		add(['# Variables d\'environnement : jamais suivies par git.', '.env*']);
+	}
+	if (!/^!\.env\.example$/m.test(next)) {
+		add(['# Modèle des variables, sans aucune valeur secrète.', '!.env.example']);
+	}
+	if (!/^\/?app\/\.fraza\/$/m.test(next)) {
+		add(['# Généré par fraza-modules sync.', 'app/.fraza/']);
+	}
+	return next;
+}
+
+/**
+ * Écrit le `.npmrc` du projet : le scope `@fraza-pro` vers le registre, rien
+ * d'autre. `@fraza` n'y figure pas : le core et les modules gratuits viennent
+ * de npmjs, le registre par défaut. Aucun jeton n'y est jamais recopié :
+ * `npx fraza-key` ajoute le jeton le jour où un module Pro arrive. Sans
+ * secret, le fichier reste suivi par git, et la machine de build sait où
+ * chercher les modules Pro.
+ *
+ * Le fichier est écrit ici, et non par `fraza-key` du core, parce qu'il doit
+ * exister avant l'installation de `@fraza/core`. Il n'est pas non plus copié
+ * depuis les gabarits : npm exclut toujours les `.npmrc` d'un paquet publié.
+ * @param {string} npmrcPath
+ */
+export function writeProjectNpmrc(npmrcPath) {
+	fs.writeFileSync(npmrcPath, `@fraza-pro:registry=${REGISTRY_URL}\n`);
+}
+
+/**
+ * En-tête de `.env.local`. Celui du modèle décrit `.env.example` : un fichier
+ * suivi par git, sans secret, lu par rien. Les trois sont faux pour
+ * `.env.local`, le seul fichier du projet qui ne doit jamais être commité.
+ */
+export const LOCAL_ENV_HEADER = [
+	'# Valeurs de cette machine, ignorées par git, lues par Next.js et les CLI',
+	'# fraza-*. Ne jamais commiter ce fichier : il porte FRAZA_ENCRYPTION_KEY.',
+	'#',
+	'# En production, ces variables se saisissent dans la plateforme',
+	"# d'hébergement. FRAZA_ENCRYPTION_KEY s'y copie telle quelle : elle ne doit",
+	'# jamais changer.',
+].join('\n');
+
+/**
+ * Remplace le bloc de commentaires qui ouvre le modèle par `LOCAL_ENV_HEADER`,
+ * ou l'ajoute quand le modèle n'en a pas.
+ * @param {string} template
+ * @returns {string}
+ */
+function withLocalHeader(template) {
+	const lines = template.split('\n');
+	let start = 0;
+	while (start < lines.length && lines[start].startsWith('#')) start += 1;
+	const rest = lines.slice(start).join('\n');
+	return start > 0 ? `${LOCAL_ENV_HEADER}\n${rest}` : `${LOCAL_ENV_HEADER}\n\n${rest}`;
+}
+
+/**
+ * Remplit les valeurs propres à cette machine dans une copie du modèle :
+ * `FRAZA_ENCRYPTION_KEY` générée et `NEXT_PUBLIC_URL` locale, sous l'en-tête
+ * de `.env.local` (`LOCAL_ENV_HEADER`).
+ *
+ * La clé n'a rien à saisir à la main : c'est 32 octets aléatoires propres au
+ * projet, que `@fraza/core/crypto` attend en 64 caractères hexadécimaux. Une clé
+ * déjà présente n'est jamais remplacée : la changer rendrait illisible tout ce
+ * qui a été chiffré avec l'ancienne.
+ * @param {string} template Contenu du `.env.example` du core.
+ * @param {{ key?: string, publicUrl?: string }} [opts]
+ * @returns {string}
+ */
+export function fillLocalEnv(template, { key = randomBytes(32).toString('hex'), publicUrl = 'http://localhost:3000' } = {}) {
+	const setEmpty = (contents, name, value) => {
+		const line = new RegExp(`^(${name}=)[ \\t]*$`, 'm');
+		if (line.test(contents)) return contents.replace(line, () => `${name}=${value}`);
+		if (new RegExp(`^${name}=`, 'm').test(contents)) return contents;
+		const separator = contents === '' || contents.endsWith('\n') ? '' : '\n';
+		return `${contents}${separator}${name}=${value}\n`;
+	};
+
+	let contents = setEmpty(withLocalHeader(template), 'FRAZA_ENCRYPTION_KEY', key);
+	contents = contents.replace(/^NEXT_PUBLIC_URL=.*$/m, () => `NEXT_PUBLIC_URL=${publicUrl}`);
+	return setEmpty(contents, 'NEXT_PUBLIC_URL', publicUrl);
+}
+
+/**
+ * Crée `.env.example` (copie du modèle du core, suivie par git) et `.env.local`
+ * (la même copie remplie pour cette machine, ignorée par git). Un fichier qui
+ * existe déjà n'est jamais remplacé.
+ * @param {string} templatePath `node_modules/@fraza/core/.env.example`.
+ * @param {string} projectDir
+ * @returns {{ example: boolean, local: boolean }} Les fichiers créés.
+ */
+export function writeEnvFiles(templatePath, projectDir) {
+	const template = fs.readFileSync(templatePath, 'utf-8');
+	const examplePath = path.join(projectDir, '.env.example');
+	const localPath = path.join(projectDir, '.env.local');
+	const created = { example: false, local: false };
+
+	if (!fs.existsSync(examplePath)) {
+		fs.writeFileSync(examplePath, template);
+		created.example = true;
+	}
+	if (!fs.existsSync(localPath)) {
+		// 0600 : le fichier porte la clé de chiffrement du projet.
+		fs.writeFileSync(localPath, fillLocalEnv(template), { mode: 0o600 });
+		created.local = true;
+	}
+	return created;
+}

package/bin/version.js

@@ -0,0 +1,2 @@
+// AUTO-GÉNÉRÉ par `fraza-module sync-version`, ne pas modifier à la main.
+export const STARTER_VERSION = '0.3.5';