@iddp/create-vefk-app 0.7.0

package/lib/ersetzen.js

@@ -0,0 +1,404 @@
+// lib/ersetzen.js
+//
+// Herzstück des Scaffolders: nimmt das frisch geklonte Template und ersetzt
+// die Platzhalter (Toolname, Marke, Auth-Profil, 2FA/Mail, Tenant-Slug) sowie
+// die @@TOKEN@@ der Infrastruktur-Dateien (Server-Slug, Port-Paar, Datum).
+//
+// Jede gezielte Ersetzung prüft, ob ihr Muster überhaupt getroffen hat.
+// Trifft eines nicht (weil sich das Template weiterentwickelt hat), bricht
+// nichts ab — die Stelle landet als Warnung im Ergebnis und wird am Ende
+// zum manuellen Nacharbeiten angezeigt. So driftet der Scaffolder nie
+// stillschweigend am Template vorbei.
+
+import { readFile, writeFile, cp, access, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Ein Muster genau einmal ersetzen; Fehltreffer → Warnung. */
+function ersetzeGenau(inhalt, muster, ersatz, beschreibung, warnungen) {
+  if (!muster.test(inhalt)) {
+    warnungen.push(beschreibung);
+    return inhalt;
+  }
+  return inhalt.replace(muster, ersatz);
+}
+
+async function bearbeiteDatei(dir, relPfad, warnungen, fn) {
+  const pfad = join(dir, relPfad);
+  let inhalt;
+  try {
+    inhalt = await readFile(pfad, "utf8");
+  } catch {
+    warnungen.push(`${relPfad}: Datei nicht gefunden`);
+    return;
+  }
+  const neu = await fn(inhalt);
+  if (neu !== inhalt) await writeFile(pfad, neu);
+}
+
+/** package.json / package-lock.json: Namen umbenennen (Lock muss mitziehen, sonst scheitert `npm ci`). */
+async function benenneNpmPaket(dir, relDir, neuerName, warnungen) {
+  await bearbeiteDatei(dir, join(relDir, "package.json"), warnungen, (inhalt) => {
+    const json = JSON.parse(inhalt);
+    json.name = neuerName;
+    return `${JSON.stringify(json, null, 2)}\n`;
+  });
+  const lockPfad = join(dir, relDir, "package-lock.json");
+  try {
+    await access(lockPfad);
+  } catch {
+    return; // kein Lockfile (z. B. Wurzel) — nichts zu tun
+  }
+  await bearbeiteDatei(dir, join(relDir, "package-lock.json"), warnungen, (inhalt) => {
+    const json = JSON.parse(inhalt);
+    json.name = neuerName;
+    if (json.packages?.[""]) json.packages[""].name = neuerName;
+    return `${JSON.stringify(json, null, 2)}\n`;
+  });
+}
+
+/**
+ * Dateien mit @@TOKEN@@-Platzhaltern der Zwei-Server-Infrastruktur. Die Liste
+ * spiegelt das Template; ein Rest-Scan über Wurzel + docs/ fängt neue Dateien.
+ */
+export const TOKEN_DATEIEN = [
+  "deploy.sh",
+  "ecosystem.config.cjs",
+  "CLAUDE-DEPLOYMENT.md",
+  "docs/01-Infrastruktur.md",
+  "docs/07-Mail-Versand.md",
+];
+
+const TOKEN_MUSTER = /@@[A-Z_]+@@/g;
+
+function heuteDeutsch() {
+  const d = new Date();
+  const zwei = (n) => String(n).padStart(2, "0");
+  return `${zwei(d.getDate())}.${zwei(d.getMonth() + 1)}.${d.getFullYear()}`;
+}
+
+/** @@TOKEN@@ in einer Datei ersetzen; unbekannte Token bleiben stehen. */
+function ersetzeTokens(inhalt, werte) {
+  return inhalt.replace(TOKEN_MUSTER, (token) => werte[token] ?? token);
+}
+
+/** Verbliebene @@TOKEN@@ in Wurzel-Dateien und docs/ melden (README wird ohnehin ersetzt). */
+async function findeTokenReste(dir, warnungen) {
+  const kandidaten = [];
+  for (const rel of [".", "docs"]) {
+    let eintraege;
+    try {
+      eintraege = await readdir(join(dir, rel), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of eintraege) {
+      if (e.isFile() && e.name !== "README.md") kandidaten.push(join(rel, e.name));
+    }
+  }
+  for (const rel of kandidaten) {
+    const inhalt = await readFile(join(dir, rel), "utf8").catch(() => "");
+    const reste = [...new Set(inhalt.match(TOKEN_MUSTER) ?? [])];
+    if (reste.length > 0) warnungen.push(`${rel}: Platzhalter ${reste.join(", ")} nicht ersetzt`);
+  }
+}
+
+function mandantTitel(slug) {
+  return slug
+    .split("-")
+    .map((teil) => teil.charAt(0).toUpperCase() + teil.slice(1))
+    .join(" ");
+}
+
+/**
+ * Wendet die Antworten auf das geklonte Template an.
+ *
+ * @param {string} dir  Wurzel des frisch geklonten Projekts
+ * @param {object} antworten  { ziel, name, authMode, genericLogin, zweiFaktor, anmeldung, adminEmails, daten,
+ *                              mail, marke, markeHell, tenantSlug, genericSlug,
+ *                              ownerEmail, slug, port, devPort, vitePort }
+ *                            genericLogin = "magic" | "password" (Login im
+ *                              offenen Bereich; fehlt er → magic),
+ *                            tenantSlug = erster Mandant (tenant/both),
+ *                            genericSlug = interner offener Bereich (generic/both),
+ *                            slug = Server-Slug (/opt/<slug>, PM2, Domain),
+ *                            port = Prod-Port (test = port+1) oder undefined,
+ *                            devPort/vitePort = lokale Dev-Ports (undefined →
+ *                              Template-Standard 3001/5173 bleibt)
+ * @returns {Promise<string[]>}  Liste der Warnungen (leer = alles ersetzt)
+ */
+export async function wendeAntwortenAn(dir, antworten) {
+  const warnungen = [];
+  const {
+    name, authMode, zweiFaktor, mail, adminEmails, daten,
+    marke, markeHell, tenantSlug, anmeldung, genericSlug, ownerEmail, slug, port, devPort, vitePort,
+  } = antworten;
+  const genericLogin = antworten.genericLogin === "password" ? "password" : "magic";
+  const mitMandanten = authMode === "tenant" || authMode === "both";
+  const mitOffen = authMode === "generic" || authMode === "both";
+
+  // --- app.config.js: zentrale Tool-Konfiguration --------------------------
+  await bearbeiteDatei(dir, "app.config.js", warnungen, (inhalt) => {
+    inhalt = ersetzeGenau(inhalt, /name:\s*"[^"]*"/, `name: ${JSON.stringify(name)}`,
+      "app.config.js: name", warnungen);
+    inhalt = ersetzeGenau(inhalt, /authMode:\s*"[^"]*"/, `authMode: "${authMode}"`,
+      "app.config.js: authMode", warnungen);
+    inhalt = ersetzeGenau(inhalt, /zweiFaktorDefault:\s*(?:true|false)/,
+      `zweiFaktorDefault: ${mitMandanten && zweiFaktor}`,
+      "app.config.js: zweiFaktorDefault", warnungen);
+    if (mitOffen) {
+      inhalt = ersetzeGenau(inhalt, /tenant:\s*"app"/, `tenant: "${genericSlug || "app"}"`,
+        "app.config.js: generic.tenant", warnungen);
+      inhalt = ersetzeGenau(inhalt, /login:\s*"(?:magic|password)"/, `login: "${genericLogin}"`,
+        "app.config.js: generic.login", warnungen);
+      // generic.zweiFaktor (nicht zweiFaktorDefault — das ist der tenant-Block)
+      inhalt = ersetzeGenau(inhalt, /(\n\s*)zweiFaktor:\s*(?:true|false)/,
+        `$1zweiFaktor: ${genericLogin === "password" && Boolean(zweiFaktor)}`,
+        "app.config.js: generic.zweiFaktor", warnungen);
+      if (ownerEmail && genericLogin === "magic") {
+        inhalt = ersetzeGenau(inhalt, /ownerEmail:\s*""/, `ownerEmail: ${JSON.stringify(ownerEmail)}`,
+          "app.config.js: generic.ownerEmail", warnungen);
+      }
+    }
+    // Admin-Bereich: Betreiber-Adressen; Datenspeicher: sqlite (Standard) | json
+    if (adminEmails?.length) {
+      inhalt = ersetzeGenau(inhalt, /emails:\s*\[[^\]]*\]/, `emails: ${JSON.stringify(adminEmails)}`,
+        "app.config.js: admin.emails", warnungen);
+    }
+    if (daten) {
+      inhalt = ersetzeGenau(inhalt, /adapter:\s*"(?:sqlite|json)"/, `adapter: "${daten}"`,
+        "app.config.js: daten.adapter", warnungen);
+    }
+    inhalt = ersetzeGenau(inhalt, /primaer:\s*"#[0-9a-fA-F]{3,8}"/, `primaer: "${marke}"`,
+      "app.config.js: marke.primaer", warnungen);
+    inhalt = ersetzeGenau(inhalt, /primaerHell:\s*"#[0-9a-fA-F]{3,8}"/, `primaerHell: "${markeHell}"`,
+      "app.config.js: marke.primaerHell", warnungen);
+    return inhalt;
+  });
+
+  // --- Paketnamen (npm ci prüft Lockfile-Namen mit!) ------------------------
+  // Technische Namen kommen überall aus dem Slug, nicht aus dem Ordnernamen —
+  // der Ordner darf lokal anders heißen (oder `.` sein).
+  await benenneNpmPaket(dir, ".", slug, warnungen);
+  await benenneNpmPaket(dir, "backend", `${slug}-backend`, warnungen);
+  await benenneNpmPaket(dir, "frontend", `${slug}-frontend`, warnungen);
+
+  // --- Frontend: Titel + Markenfarben ---------------------------------------
+  await bearbeiteDatei(dir, "frontend/index.html", warnungen, (inhalt) =>
+    ersetzeGenau(inhalt, /<title>[^<]*<\/title>/, `<title>${name}</title>`,
+      "frontend/index.html: <title>", warnungen));
+
+  await bearbeiteDatei(dir, "frontend/src/index.css", warnungen, (inhalt) => {
+    inhalt = ersetzeGenau(inhalt, /--iddp:\s*#[0-9a-fA-F]{3,8};/, `--iddp: ${marke};`,
+      "frontend/src/index.css: --iddp", warnungen);
+    inhalt = ersetzeGenau(inhalt, /--iddp-light:\s*#[0-9a-fA-F]{3,8};/, `--iddp-light: ${markeHell};`,
+      "frontend/src/index.css: --iddp-light", warnungen);
+    return inhalt;
+  });
+
+  // --- .env.example + ecosystem-Beispiel: Anzeigename überall ---------------
+  await bearbeiteDatei(dir, ".env.example", warnungen, (inhalt) => {
+    if (!inhalt.includes("VEFK Tool")) warnungen.push(".env.example: „VEFK Tool“ nicht gefunden");
+    inhalt = inhalt.replaceAll("VEFK Tool", name);
+    if (mail) {
+      // SMTP-Block einkommentieren, damit die Werte direkt ausgefüllt werden.
+      inhalt = inhalt.replace(/^# (SMTP_[A-Z_]+=)/gm, "$1");
+    }
+    if (devPort !== undefined) {
+      inhalt = ersetzeGenau(inhalt, /^PORT=\d+$/m, `PORT=${devPort}`, ".env.example: PORT", warnungen);
+    }
+    return inhalt;
+  });
+
+  // --- Lokale Dev-Ports (Backend = Prod-Port, Vite = 51xx) ------------------
+  // Gezielte Ersetzungen statt @@TOKEN@@: das Template bleibt ohne Scaffolder
+  // lauffähig (3001/5173), und ein Fehltreffer wird hier gemeldet — der
+  // Token-Rest-Scan sieht frontend/ nicht.
+  if (devPort !== undefined) {
+    await bearbeiteDatei(dir, "frontend/vite.config.js", warnungen, (inhalt) => {
+      inhalt = ersetzeGenau(inhalt, /port:\s*\d+/, `port: ${vitePort}`,
+        "frontend/vite.config.js: server.port", warnungen);
+      inhalt = ersetzeGenau(inhalt, /http:\/\/localhost:\d+/, `http://localhost:${devPort}`,
+        "frontend/vite.config.js: proxy → Backend", warnungen);
+      return inhalt;
+    });
+    await bearbeiteDatei(dir, "docs/08-2FA-Login.md", warnungen, (inhalt) => {
+      if (!inhalt.includes("localhost:3001")) warnungen.push("docs/08-2FA-Login.md: localhost:3001 (curl-Beispiele) nicht gefunden");
+      return inhalt.replaceAll("localhost:3001", `localhost:${devPort}`);
+    });
+    await bearbeiteDatei(dir, "CLAUDE-DEPLOYMENT.md", warnungen, (inhalt) => {
+      inhalt = ersetzeGenau(inhalt, /127\.0\.0\.1:3001/, `127.0.0.1:${devPort}`,
+        "CLAUDE-DEPLOYMENT.md: Dev-Backend-Port", warnungen);
+      inhalt = ersetzeGenau(inhalt, /Vite auf :5173/, `Vite auf :${vitePort}`,
+        "CLAUDE-DEPLOYMENT.md: Dev-Vite-Port", warnungen);
+      inhalt = ersetzeGenau(inhalt, /Proxy → :3001/, `Proxy → :${devPort}`,
+        "CLAUDE-DEPLOYMENT.md: Dev-Proxy-Port", warnungen);
+      return inhalt;
+    });
+  }
+
+  // --- Infrastruktur: deploy.sh, ecosystem.config.cjs, CLAUDE-DEPLOYMENT.md, docs
+  // Ohne Port bleiben @@PORT_*@@ stehen — deploy.sh bricht dann bewusst ab,
+  // ecosystem.config.cjs lädt nicht. Beides landet als Warnung.
+  const werte = {
+    "@@APP@@": slug,
+    "@@APPNAME@@": name,
+    "@@DATUM@@": heuteDeutsch(),
+  };
+  if (port !== undefined) {
+    werte["@@PORT_PROD@@"] = String(port);
+    werte["@@PORT_TEST@@"] = String(port + 1);
+  } else {
+    warnungen.push("Port-Paar nicht gesetzt (--port): @@PORT_PROD@@/@@PORT_TEST@@ in deploy.sh, ecosystem.config.cjs und Docs von Hand eintragen");
+  }
+  for (const rel of TOKEN_DATEIEN) {
+    await bearbeiteDatei(dir, rel, warnungen, (inhalt) => ersetzeTokens(inhalt, werte));
+  }
+  if (port !== undefined) await findeTokenReste(dir, warnungen);
+
+  // --- Erster Mandant (tenant/both, optional) -------------------------------
+  if (mitMandanten && tenantSlug) {
+    const quelle = join(dir, "backend/data/tenants/_muster");
+    const zielDir = join(dir, "backend/data/tenants", tenantSlug);
+    try {
+      await cp(quelle, zielDir, { recursive: true, errorOnExist: true, force: false });
+      await bearbeiteDatei(dir, join("backend/data/tenants", tenantSlug, "dashboard-config.json"),
+        warnungen, (inhalt) => {
+          const json = JSON.parse(inhalt);
+          json.titel = mandantTitel(tenantSlug);
+          // Explizit setzen: der Dateiwert übersteuert zweiFaktorDefault (docs/08).
+          json.zweiFaktor = zweiFaktor;
+          // Anmeldeart: konto (Default) | zugang — später in /admin umschaltbar (docs/08).
+          json.anmeldung = anmeldung === "zugang" ? "zugang" : "konto";
+          return `${JSON.stringify(json, null, 2)}\n`;
+        });
+    } catch (fehler) {
+      warnungen.push(`Mandant „${tenantSlug}“ anlegen: ${fehler.message}`);
+    }
+  }
+
+  // --- beispiel-Mandant entfernen -------------------------------------------
+  // Sobald ein echter erster Mandant existiert (oder das Tool gar keine
+  // Mandanten hat: generic), ist der Demo-Mandant nur noch im Weg. Er
+  // verschwindet samt seiner Whitelist in .gitignore. Der erste Mandant erbt
+  // die Whitelist NICHT: er ist ein echter Kunde, seine Nutzdaten (Mitarbeiter,
+  // Dokumente, Änderungshistorie) gehören nie ins Git — es bleibt bei
+  // `tenants/* + !_muster`; auf dem Server entsteht der Ordner aus _muster.
+  // Nur der Wurzel-Redirect in App.jsx zeigt auf ihn. Ohne ersten Mandanten
+  // (tenant/both ohne --tenant) bleibt beispiel als Demo stehen.
+  const beispielWeg = (mitMandanten && Boolean(tenantSlug)) || authMode === "generic";
+  if (beispielWeg) {
+    await rm(join(dir, "backend/data/tenants/beispiel"), { recursive: true, force: true });
+    await bearbeiteDatei(dir, ".gitignore", warnungen, (inhalt) => {
+      inhalt = ersetzeGenau(inhalt,
+        /^# === Tenant-Daten — nur _muster und beispiel im Repo ===$/m,
+        "# === Tenant-Daten — nur _muster im Repo ===",
+        ".gitignore: Kommentar „Tenant-Daten“", warnungen);
+      inhalt = ersetzeGenau(inhalt,
+        /^!backend\/data\/tenants\/beispiel\/\n/m, "",
+        ".gitignore: Whitelist des beispiel-Mandanten", warnungen);
+      inhalt = ersetzeGenau(inhalt,
+        /^backend\/data\/tenants\/beispiel\/users\.json\n/m, "",
+        ".gitignore: users.json des beispiel-Mandanten", warnungen);
+      return inhalt;
+    });
+    if (mitMandanten && tenantSlug) {
+      await bearbeiteDatei(dir, "frontend/src/App.jsx", warnungen, (inhalt) => ersetzeGenau(inhalt,
+        /to="\/beispiel"/, `to="/${tenantSlug}"`,
+        "frontend/src/App.jsx: Wurzel-Redirect /beispiel → erster Mandant", warnungen));
+    }
+  }
+
+  // --- README des neuen Tools (ersetzt das Template-README) -----------------
+  await writeFile(join(dir, "README.md"), erzeugeReadme(antworten));
+
+  return warnungen;
+}
+
+function erzeugeReadme({ name, authMode, genericLogin, zweiFaktor, mail, tenantSlug, anmeldung, genericSlug, adminEmails, daten, slug, port, devPort, vitePort }) {
+  const passwortOffen = genericLogin === "password";
+  const offenText = passwortOffen
+    ? `Login mit E-Mail + Passwort${zweiFaktor ? " + E-Mail-2FA" : ""} (\`generic.login: "password"\`), Nutzer legt der Admin an`
+    : "passwortloser Magic-Code-Login per E-Mail (`generic.login: \"magic\"`)";
+  const authZeile = {
+    tenant: `Mandanten-Tool (\`authMode: "tenant"\`) — Login mit E-Mail + Passwort${zweiFaktor ? " + E-Mail-2FA" : ""}, Tenant-Guard aktiv.`,
+    generic: `Mandantenloses Tool (\`authMode: "generic"\`) — ${offenText}.`,
+    both: `Kombi-Tool (\`authMode: "both"\`) — Mandanten-Bereiche unter \`/:tenant\` (Passwort${zweiFaktor ? " + 2FA" : ""}) plus offener Bereich unter \`/uebersicht\` (${offenText}; interner Slug: \`${genericSlug || "app"}\`).`,
+  }[authMode];
+  const mitMandanten = authMode === "tenant" || authMode === "both";
+  const anmeldungText = anmeldung === "zugang"
+    ? "Anmeldung **nur mit dem gemeinsamen Mandanten-Passwort** (ohne E-Mail) — vor dem ersten Login `npm run zugang` bzw. in `/admin` setzen"
+    : "Anmeldung mit **Nutzerkonten** (E-Mail + Passwort oder E-Mail-Code; ein Mandanten-Zugang ist zusätzlich möglich)";
+  const mandantZeile = mitMandanten && tenantSlug
+    ? `\nErster Mandant: \`backend/data/tenants/${tenantSlug}/\` (aus \`_muster\` erzeugt; der Demo-Mandant \`beispiel\` wurde entfernt, \`/\` leitet nach \`/${tenantSlug}\`). ${anmeldungText}; umschaltbar in \`/admin\` → Einstellungen. Der Ordner ist **nicht im Git** (echter Mandant, \`docs/05\`) — auf dem Server ebenfalls aus \`_muster\` anlegen.\n`
+    : mitMandanten
+      ? "\nNoch kein eigener Mandant — der Demo-Mandant `beispiel` steht als Vorlage (Slug bei Bedarf umbenennen, `.gitignore` + `App.jsx` mitziehen).\n"
+      : "";
+  const zugangZeile = mitMandanten
+    ? "npm run zugang                 # optional: Mandanten-Zugang (nur Passwort, kein Konto)\n"
+    : "";
+  const mailHinweis = mail
+    ? "SMTP-Zugangsdaten in `backend/.env` eintragen (Regeln: `docs/07`)."
+    : "SMTP ist noch nicht konfiguriert — für 2FA/Magic-Code später `docs/07` folgen.";
+  const datenZeile = daten === "json"
+    ? "Datenspeicher: JSON-Dateien je Mandant (`daten.adapter: \"json\"`); Wechsel auf SQLite später per `npm run migrate:sqlite`."
+    : "Datenspeicher: SQLite (`backend/data/app.sqlite`, nie im Git); vorhandene JSON-Mandanten werden beim ersten Start übernommen.";
+  const adminZeile = `Admin-Bereich: \`/admin\` — Mandanten, Nutzer, Zugänge, Admins, Protokoll. Anmeldung mit Google-Konto ` +
+    `(Suite-OAuth-Client aus \`/etc/vefk-suite/env\` bzw. \`~/.config/vefk-suite/env\`, Redirect-URI \`/api/admin/auth/google/callback\` zeigt die Login-Seite) ` +
+    `oder per E-Mail-Code (SMTP). Zugelassen: ${adminEmails?.length ? adminEmails.map((e) => `\`${e}\``).join(", ") : "die Adressen in `app.config.js → admin.emails`"} (\`docs/09\`).`;
+  const portProd = port ?? "<prod-port>";
+  const portTest = port ? port + 1 : "<test-port>";
+  const lokalBackend = devPort ?? 3001;
+  const lokalVite = vitePort ?? 5173;
+  return `# ${slug}
+
+**${name}** — ein Tool der VEFK-Tools-Suite, erzeugt mit \`create-vefk-app\`
+aus \`vefk-app-template\`.
+
+${authZeile}
+${mandantZeile}
+${datenZeile}
+
+${adminZeile}
+
+## Loslegen
+
+\`\`\`bash
+# backend/.env hat create-vefk-app angelegt (Dev-Flags + zufälliges SESSION_SECRET);
+# fehlt sie: cp .env.example backend/.env und SESSION_SECRET setzen.
+npm run install:all            # zieht @iddp/vefk-ui von GitHub, @iddp/vefk-app-kit von npm
+npm run create-user            # ersten Nutzer anlegen (ohne Passwort = Login per E-Mail-Code)
+${zugangZeile}npm run dev                    # Backend :${lokalBackend} + Vite :${lokalVite} zusammen (Ctrl-C beendet beide)
+\`\`\`
+
+Einzeln: \`npm run dev:backend\` / \`npm run dev:frontend\` (Vite mit strictPort, Proxy → :${lokalBackend}).
+
+${mailHinweis}
+
+## Deployen (zwei Server, kein Dev-Server)
+
+| | prod | test |
+|---|---|---|
+| Server / Ordner | \`prod-server\` · \`/opt/${slug}\` | \`test-server\` · \`/opt/${slug}-test\` |
+| PM2 / Port (\`127.0.0.1\`) | \`${slug}\` · ${portProd} | \`${slug}-test\` · ${portTest} |
+
+\`\`\`bash
+./deploy.sh test     # auf Zuruf
+./deploy.sh prod     # nur mit ausdrücklicher Erlaubnis des Betreibers
+\`\`\`
+
+Details, Erstinbetriebnahme und Regeln: \`CLAUDE-DEPLOYMENT.md\`. Secrets liegen
+als \`backend/.env\` auf dem Server; \`ecosystem.config.cjs\` ist secret-frei im Repo.
+
+## Wo steht was
+
+| Pfad | Inhalt |
+|---|---|
+| \`app.config.js\` | Zentrale Tool-Konfiguration (Name, Auth-Profil, Marke) |
+| \`AGENTS.md\` / \`CLAUDE.md\` | Betriebsanleitung für Coding-Agenten |
+| \`CLAUDE-DEPLOYMENT.md\` | Steckbrief auf beiden Servern, Deploy-Regeln |
+| \`docs/00\`–\`09\` | Blueprint der Suite (Architektur, Sicherheit, Mail, 2FA, Admin-Bereich) |
+| \`docs/06\` | Start-Checkliste für die ersten eigenen Seiten |
+
+Tests: \`npm test\` (Sicherheits-Smoke-Tests — müssen grün bleiben).
+`;
+}

package/lib/farben.js

@@ -0,0 +1,66 @@
+// lib/farben.js
+//
+// Markenfarbe: Validierung + Ableitung der hellen Variante.
+// Das Template kennt zwei Markenwerte (--iddp und --iddp-light, docs/04).
+// Wer nur EINE Farbe angibt, bekommt die helle Variante automatisch
+// abgeleitet (gleicher Farbton, mehr Sättigung, mehr Helligkeit) —
+// beim IDDP-Violett #6667ab landet das fast exakt auf dem bisherigen
+// Handwert #8a8bd4.
+
+/** #abc oder #aabbcc (Groß-/Kleinschreibung egal)? */
+export function istHexFarbe(wert) {
+  return typeof wert === "string" && /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(wert);
+}
+
+/** #abc → #aabbcc, alles kleingeschrieben. */
+export function normalisiereHex(wert) {
+  let hex = wert.toLowerCase();
+  if (hex.length === 4) {
+    hex = `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`;
+  }
+  return hex;
+}
+
+function hexZuHsl(hex) {
+  const n = normalisiereHex(hex);
+  const r = parseInt(n.slice(1, 3), 16) / 255;
+  const g = parseInt(n.slice(3, 5), 16) / 255;
+  const b = parseInt(n.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  const d = max - min;
+  if (d === 0) return { h: 0, s: 0, l };
+  const s = d / (1 - Math.abs(2 * l - 1));
+  let h;
+  if (max === r) h = 60 * (((g - b) / d) % 6);
+  else if (max === g) h = 60 * ((b - r) / d + 2);
+  else h = 60 * ((r - g) / d + 4);
+  if (h < 0) h += 360;
+  return { h, s, l };
+}
+
+function hslZuHex({ h, s, l }) {
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - c / 2;
+  let r = 0, g = 0, b = 0;
+  if (h < 60) [r, g, b] = [c, x, 0];
+  else if (h < 120) [r, g, b] = [x, c, 0];
+  else if (h < 180) [r, g, b] = [0, c, x];
+  else if (h < 240) [r, g, b] = [0, x, c];
+  else if (h < 300) [r, g, b] = [x, 0, c];
+  else [r, g, b] = [c, 0, x];
+  const kanal = (v) => Math.round((v + m) * 255).toString(16).padStart(2, "0");
+  return `#${kanal(r)}${kanal(g)}${kanal(b)}`;
+}
+
+/** Helle Markenvariante aus der Primärfarbe ableiten. */
+export function helleVariante(hex) {
+  const { h, s, l } = hexZuHsl(hex);
+  return hslZuHex({
+    h,
+    s: Math.min(1, s * 1.6),
+    l: Math.min(0.92, l + 0.15),
+  });
+}