@mostajs/env-manager 0.1.0

package/README.md

@@ -0,0 +1,5 @@
+# @mostajs/env-manager
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+
+Gestionnaire de fichiers **`.env`** : lecture, application dans `process.env`, et **persistance** (mise à jour des lignes existantes + ajout des nouvelles, commentaires préservés). Sans dépendance. Extrait de l app AgoraScope.

package/llms.txt

@@ -0,0 +1,9 @@
+# @mostajs/env-manager — fiche LLM
+> Gestionnaire de fichiers .env : lecture, application (process.env), persistance (update lignes + ajout). Sans dépendance.
+
+## EXPORTS
+parseEnv(text) -> obj · readEnvFile(path) -> obj · applyEnvFile(path,{env,override}) -> appliquées · updateEnvFile(path,kv) -> bool (persiste, préserve commentaires/ordre) · createEnvManager(path,{env}) -> { read, apply, update(=persiste+applique), get, path }
+
+## PIÈGES
+- applyEnvFile : override=false (défaut) → l env SYSTÈME prévaut sur le fichier.
+- updateEnvFile : met à jour les lignes existantes, AJOUTE les nouvelles, conserve commentaires.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mostajs/env-manager",
+  "version": "0.1.0",
+  "description": "Gestionnaire de fichiers .env : lecture, application dans process.env, et persistance (update des lignes + ajout). Sans dépendance.",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "llms.txt"
+  ],
+  "keywords": [
+    "dotenv",
+    "env",
+    "config",
+    "persistence",
+    "mostajs"
+  ],
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.3.0"
+  },
+  "scripts": {
+    "test": "node test-scripts/unit/env-manager.test.mjs && node examples/run.mjs"
+  }
+}

package/src/index.js

@@ -0,0 +1,55 @@
+// @mostajs/env-manager — gestionnaire de fichiers .env : lecture, application (process.env),
+// et PERSISTANCE (mise à jour des lignes, ajout des nouvelles). Sans dépendance. LOGIQUE PURE + I/O fichier.
+// @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+import fs from 'node:fs';
+
+/** Parse un texte .env → objet { CLE: valeur } (commentaires/ lignes vides ignorés ; guillemets retirés). */
+export function parseEnv(text = '') {
+  const out = {};
+  for (const line of String(text).split('\n')) {
+    const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if (m && !line.trimStart().startsWith('#')) out[m[1]] = m[2].replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+/** Lit un fichier .env → objet (vide si absent). */
+export function readEnvFile(path) { try { return parseEnv(fs.readFileSync(path, 'utf8')); } catch { return {}; } }
+
+/**
+ * Applique un .env dans process.env (ou un env cible).
+ * @param {string} path
+ * @param {{ env?, override? }} [opts]  override=false (défaut) : l'env système prévaut sur le fichier.
+ * @returns {object} les paires effectivement appliquées
+ */
+export function applyEnvFile(path, { env = process.env, override = false } = {}) {
+  const parsed = readEnvFile(path); const applied = {};
+  for (const [k, v] of Object.entries(parsed)) if (override || env[k] === undefined) { env[k] = v; applied[k] = v; }
+  return applied;
+}
+
+/**
+ * PERSISTE des paires clé=valeur dans le fichier .env : met à jour les lignes existantes,
+ * ajoute les nouvelles, **préserve** commentaires et ordre. Crée le fichier au besoin.
+ * @returns {boolean} succès
+ */
+export function updateEnvFile(path, kv = {}) {
+  let lines = []; try { lines = fs.readFileSync(path, 'utf8').split('\n'); } catch { /* nouveau */ }
+  const seen = new Set();
+  lines = lines.map((l) => { const m = l.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/); if (m && kv[m[1]] !== undefined) { seen.add(m[1]); return `${m[1]}=${kv[m[1]]}`; } return l; });
+  for (const [k, v] of Object.entries(kv)) if (!seen.has(k)) lines.push(`${k}=${v}`);
+  // TOUJOURS terminer par un saut de ligne (sinon un append externe se concatène à la dernière ligne).
+  try { fs.writeFileSync(path, lines.join('\n').replace(/\n+$/, '') + '\n'); return true; } catch { return false; }
+}
+
+/** Façade pratique : un gestionnaire lié à un chemin. */
+export function createEnvManager(path, { env = process.env } = {}) {
+  return {
+    path,
+    read: () => readEnvFile(path),
+    apply: (opts) => applyEnvFile(path, { env, ...opts }),
+    update: (kv) => { const ok = updateEnvFile(path, kv); if (ok) Object.assign(env, kv); return ok; },  // persiste + applique au runtime
+    get: (k) => readEnvFile(path)[k],
+  };
+}
+export default { parseEnv, readEnvFile, applyEnvFile, updateEnvFile, createEnvManager };