create-vefk-app

Scaffolder der VEFK-Tools-Suite: erzeugt aus vefk-app-template ein neues, sofort startbares Tool — Template klonen, Platzhalter ersetzen (Toolname, Markenfarbe, Auth-Profil, 2FA/Mail, erster Mandant, Server-Slug, Port-Paar, lokale Dev-Ports), backend/.env anlegen, git init + Initial-Commit. Das Ergebnis ist für die Zwei-Server-Welt (test/prod, deploy-User, 127.0.0.1) vorbereitet — deploy.sh, ecosystem.config.cjs und CLAUDE-DEPLOYMENT.md sind ausgefüllt.

npm create @iddp/vefk-app@latest <ordner>
npm create @iddp/vefk-app@latest .          # in den aktuellen, leeren Ordner
# fragt interaktiv: Zielordner (. = aktueller Ordner), Anzeigename, Auth-Profil
# (Standard both), Login ohne Mandant (E-Mail + Passwort oder Magic-Code), 2FA,
# Markenfarbe, erster Mandant, Server-Slug, Prod-Port (aus dem Port-Register — dort
# auch eintragen!), npm install (Standard ja) …

Login-Wege, die das Ergebnis kennt (Kit ≥ 0.6.0): je Mandant E-Mail + Passwort (+ 2FA), E-Mail-Code für Nutzer, die create-user ohne Passwort angelegt hat, und ein Mandanten-Zugang nur mit Passwort (npm run zugang); ohne Mandant E-Mail + Passwort (--login password) oder Magic-Code mit Selbst-Registrierung (--login magic).

Ordnername = Server-Slug (/opt/<slug>, PM2 <slug>, <slug>.<domain>, Paketnamen): nur a-z, 0-9, -, kein Präfix-Zwang — gbu, seminar, vefkev-user sind gute Namen. --slug übersteuert, wenn der Ordner lokal anders heißen soll. Ein schon vorhandener Ordner ist als Ziel erlaubt, solange er leer ist; sonst bricht das CLI ab, ohne etwas anzufassen.

Solange das Paket noch nicht auf npm liegt, geht derselbe Aufruf direkt vom Repo:

npx github:esgoet/create-vefk-app <ordner>

Voraussetzungen

• Node ≥ 20.11; die Suite läuft lokal und auf den Servern auf Node 24 (.nvmrc). Vor dem Aufruf dieselbe Version aktiv haben (fnm use 24 / nvm use 24): native Module (better-sqlite3, bcrypt) werden für das aktive Node gebaut; wechselt nvm nach dem cd ins Projekt auf eine andere Version, startet das Backend mit ERR_DLOPEN_FAILED. Der Scaffolder warnt bei Abweichung und nennt npm --prefix backend rebuild.
• git mit Zugriff auf das private Repo esgoet/vefk-app-template (dieselben Credentials, die auch npm install für die @iddp-git-Dependencies braucht)

Optionen (für Skripte / nicht-interaktiv)

create-vefk-app [<ordner>] [Optionen]

  --dir <pfad>           Zielordner (statt des Positionsarguments; `.` erlaubt)
  --name <text>          Anzeigename (Header, Mail-Betreff)
  --auth <profil>        tenant | generic | both (Standard: both)
  --login <verfahren>    Login ohne Mandant (generic/both): magic (Code per E-Mail,
                         Nutzer legen sich selbst an; Standard) | password (E-Mail + Passwort,
                         Nutzer legt der Admin an — der „normale" Login)
  --brand <#rrggbb>      Markenfarbe (helle Variante wird abgeleitet; --brand-light überschreibt)
  --two-factor / --no-two-factor   E-Mail-2FA nach dem Passwort für Mandanten-Logins (tenant/both)
                         bzw. den Passwort-Login (--login password); gilt nicht für Magic-Code
                         und Mandanten-Zugang; pro Mandant später in /admin umschaltbar
  --mail / --no-mail     Mail-Versand vorgesehen (2FA/Magic-Code). SMTP-Zugang kommt suite-weit
                         aus /etc/vefk-suite/env, das Tool setzt nur SMTP_FROM
  --tenant <slug>        erster Mandant (tenant/both)
  --anmeldung <art>      erster Mandant: konto (E-Mail + Passwort / E-Mail-Code, Standard) |
                         zugang (nur gemeinsames Mandanten-Passwort ohne E-Mail; Passwort danach per
                         npm run zugang oder /admin setzen); später in /admin → Einstellungen umschaltbar
  --generic-tenant <slug> optional: interner Slug des offenen Bereichs (Standard app, wird nicht gefragt)
  --owner-email <mail>   optional (--login magic): weitere Adresse, die beim Auto-Anlegen admin wird
                         (die Adressen aus --admin-email sind es ohnehin; wird nicht gefragt)
  --admin-email <mail>   Admin-Bereich /admin (Google-Konto oder E-Mail-Code): darf sich anmelden;
                         mehrfach oder Komma-getrennt (Standard: Betreiber-Adressen aus dem Template)
  --daten <adapter>      sqlite (Standard: eine Datei backend/data/app.sqlite) | json (Datei je Collection)
  --slug <slug>          Server-Slug → /opt/<slug>, PM2 <slug>, <slug>.<domain> (Standard: Ordnername)
  --port <nnnn>          Prod-Port aus dem Port-Register, test = +1. Kein Standardwert:
                         ohne --port bleiben die @@PORT_*@@-Token stehen und werden gemeldet.
                         Lokal: Backend = Prod-Port, Vite = 51 + letzte zwei Stellen (3130 → 3130/5130)
  --dev-port <nnnn>      lokaler Backend-Port, falls der Prod-Port lokal belegt ist (Vite folgt)
  --template <pfad|url>  andere Template-Quelle (auch lokaler Pfad — gut zum Testen)
  --install              nach dem Anlegen npm run install:all (Standard, auch mit --yes)
  --no-install           … überspringen
  --no-git               kein git init / Initial-Commit
  --no-local-env         keine backend/.env anlegen (Standard: Kopie von .env.example mit
                         NODE_ENV=development, VEFK_DEV_LOGIN=true, zufälligem SESSION_SECRET)
  --yes                  nichts fragen, Standardwerte nehmen

Beispiele:

npx @iddp/create-vefk-app protokolle --name "Prüfprotokolle" \
  --auth tenant --two-factor --brand "#0b5b52" --tenant kunde-a --port 3090 --yes

# mandantenlos mit „normalem" Login (E-Mail + Passwort, kein Magic-Code):
npx @iddp/create-vefk-app intern --name "Intern" --auth generic --login password --port 3092 --yes

# in einen schon angelegten, leeren Ordner (Slug = Ordnername):
mkdir vefkev-user && cd vefkev-user
npx @iddp/create-vefk-app . --name "VEFK e.V. Mitglieder" --auth tenant --port 3130 --install --yes

Was das CLI ersetzt

| Stelle | Wert | |---|---| | app.config.js | Name, authMode (tenant/generic/both), zweiFaktorDefault, generic-Slug/login/zweiFaktor/Owner, Markenfarben | | package.json × 3 + beide package-lock.json | Paketnamen aus dem Slug (npm ci prüft die Lock-Namen mit) | | frontend/index.html, frontend/src/index.css | <title>, --iddp / --iddp-light | | .env.example | APP_NAME, SMTP_FROM (Display-Name bereinigt nach docs/07, Absender [email protected]), PORT = lokaler Dev-Port | | frontend/vite.config.js, docs/08, CLAUDE-DEPLOYMENT.md (Dev-Block) | lokale Dev-Ports (nur mit --port/--dev-port; sonst bleibt 3001/5173) | | backend/.env (neu, gitignored) | Kopie von .env.example mit Dev-Flags + zufälligem SESSION_SECRET — nie ausgegeben | | deploy.sh, ecosystem.config.cjs, CLAUDE-DEPLOYMENT.md, docs/01, docs/07 | @@APP@@ (Server-Slug), @@APPNAME@@, @@PORT_PROD@@/@@PORT_TEST@@, @@DATUM@@; Rest-Scan meldet vergessene Token in Wurzel + docs/ | | backend/data/tenants/<slug>/ | erster Mandant aus _muster, zweiFaktor explizit gesetzt | | backend/data/tenants/beispiel/, .gitignore, frontend/src/App.jsx | mit erstem Mandanten (oder generic): Demo-Mandant beispiel entfernt samt .gitignore-Whitelist (der erste Mandant ist ein echter Kunde und bleibt ungetrackt), Wurzel-Redirect / → /<slug> | | README.md | wird durch ein Projekt-README des neuen Tools ersetzt |

Trifft eine Ersetzung nicht (weil sich das Template weiterentwickelt hat), bricht nichts ab — das CLI listet die Stelle am Ende als Warnung zum Nachprüfen.

Entwurfsentscheidungen

• git clone statt degit: degit lädt GitHub-Tarballs und scheitert am privaten Template-Repo ohne eigene Token-Konfiguration. git clone --depth 1 + .git entfernen nutzt die ohnehin eingerichteten Git-Credentials und kann zusätzlich lokale Pfade (--template ../vefk-app-template).
• Zero-Dependency: nur Node-Bordmittel (node:util parseArgs, node:readline/promises, node:test) — Suite-Linie „nativ statt Extra-Deps".

Entwickeln & Testen

npm test                        # node:test — Unit + End-to-End gegen die Fixture
node bin/create-vefk-app.js probe --yes --no-install --port 3090 --template ../vefk-app-template

Die Fixture (test/fixtures/mini-template/) friert die Template-Stellen ein, die das CLI anfasst. Ändert sich das Template an diesen Stellen, Fixture nachziehen.

Auf npm veröffentlichen

Das Paket heißt @iddp/create-vefk-app (npm-Org iddp, publishConfig.access: public; files-Whitelist: nur bin/, lib/, README). Öffentlich sind der Scaffolder und @iddp/vefk-app-kit; Template und @iddp/vefk-ui bleiben private Repos.

npm login
npm publish            # Browser-Verifizierung → läuft nur im eigenen Terminal
npm view @iddp/create-vefk-app version

Danach funktioniert npm create @iddp/vefk-app@latest für alle, die Git-Zugriff auf das Template-Repo haben. Der frühere Name create-vefk-app (bis 0.6.0) ist per npm deprecate auf das neue Paket verwiesen. Falle: npm create nutzt den npx-Cache (~/.npm/_npx) — zum Testen immer @latest anhängen.