w1-app-creator

Standalone Project Generator für W1 System Anwendungen.

Detaillierte Architekturdokumentation: doc/skeleton-project-generator.md

Push- und Deploy-Nutzung: doc/workspace-push-usage.md

Verwendung

# Aus dem Parent-Verzeichnis (wo w1-system-core-sceleton liegt)
node w1-app-creator/create-project.mjs

# Mit Optionen
node w1-app-creator/create-project.mjs --clone-deps --clone-org werk1

Voraussetzungen

• Node.js >= 20
• Ohne --clone-deps: w1-system-core-sceleton und w1-system-core-v2 im Parent oder über --skeleton/--core-v2 angeben
• Mit --clone-deps: Alles wird automatisch in den Workspace geklont

core-v2 wird nur bei Vollprojekt benötigt – nicht bei --skeleton-only. Das Skeleton selbst referenziert keine core-v2-Dateien.

CLI-Optionen

Alle Optionen sind optional – ohne Angabe werden sie interaktiv abgefragt. CLI-Argumente überschreiben die interaktiven Defaults.

Option	Beschreibung
--dry-run	Nur simulieren, keine Dateien schreiben
--force	Zielverzeichnis ohne Rückfrage überschreiben
--clone-deps	@werk1-Pakete von GitHub klonen (interaktiv abgefragt wenn nicht gesetzt)
--clone-git-host <host>	Git-Host (interaktiv, Default: github.com, z.B. werk1.github.com)
--clone-branch <branch>	Branch für Klone (interaktiv, Default: main)
--clone-org <org>	GitHub-Organisation (interaktiv, Default: aus Projekt-Setup)
--skeleton <path>	Pfad zu w1-system-core-sceleton (überspringt Auto-Detection)
--core-v2 <path>	Pfad zu w1-system-core-v2 (überspringt Auto-Detection)

Workspace-Modus

Mit --clone-deps wird automatisch ein isoliertes Workspace erstellt, das alles enthält – auch sceleton und core-v2:

workspace-<projektname>/
├── <projektname>/                ← generierte App
├── w1-system-core-sceleton/       ← geklont (immer)
├── w1-system-core-v2/             ← geklont (nur bei Vollprojekt)
├── w1-system-carouselblock/       ← geklont
├── w1-system-videoblock/          ← geklont
└── ...

Wichtig:

• Im Workspace-Modus wird sceleton immer ins Workspace geklont. core-v2 wird nur bei Vollprojekt geklont – --skeleton-only benötigt es nicht.
• Bestehende Repos werden mit git pull aktualisiert.
• @werk1-Pakete werden in definierter Reihenfolge gebaut (Basis → Blöcke → Media → IDML/Article).
• Einzelne Build-Fehler stoppen nicht den gesamten Prozess – fehlgeschlagene Pakete werden geloggt.

Struktur

w1-app-creator/
├── create-project.mjs      # Einstiegspunkt
├── package.json            # Tool-Metadaten
├── lib/                    # Generator-Logik
│   ├── prompt.mjs          # Interaktive Abfragen
│   ├── resolve-deps.mjs    # Modul-Katalog
│   ├── copy-skeleton.mjs   # Skeleton kopieren
│   ├── copy-modules.mjs    # Modul-Dateien kopieren
│   ├── render-templates.mjs # Templates rendern
│   ├── clone-deps.mjs      # @werk1 Pakete klonen
│   └── post-gen.mjs        # Post-Generation Hooks
├── templates/              # Alle Template-Dateien (*.tpl.mjs)
├── autodeploy-multi/       # Build- und Deploy-Scripts (werden bei jedem Push aktualisiert)
│   ├── build_and_deploy_multi-repo.sh
│   ├── multi_repo_build.sh
│   ├── Dockerfile_Multi
│   └── Dockerfile_Multi_Autodeploy_Builder
└── doc/                    # Dokumentation

Abhängigkeiten

• Verwendet w1-system-core-sceleton für Skeleton-Quellen und Templates
• Verwendet w1-system-core-v2 für optionale Modul-Dateien
• Beide werden automatisch geklont wenn nicht vorhanden

Im generierten Projekt erzeugte Dateien

Der Creator rendert u.a. folgende Dateien ins Zielprojekt:

• README.md – projektspezifisches README mit allen relevanten Scripts (dev, build, update, Push, Autodeploy), Docker-Compose-Workflow (dev:docker*) und Beschreibung des autodeploy/multi/-Stacks. Mode-abhaengig (Workspace vs. klassisch).
• W1_GENERATION_REPORT.md – Abschlussbericht ueber aktivierte Module, kopierte Dateien und erzeugte Templates.
• scripts/push.sh / push.bat / push.ps1 – klassischer Push auf den Build-Server.
• scripts/workspace-push-node.mjs – Node-basierter Push fuer den Workspace-Modus (erstellt Git-Bundles aller @werk1-Pakete).
• scripts/workspace-update.mjs – aktualisiert im Workspace-Modus alle via file:-Deps eingebundenen @werk1-Pakete per git pull und baut nur Pakete neu, deren HEAD sich geaendert hat (siehe npm run update).
• scripts/docker-dev-app.sh / scripts/run-docker-dev.mjs – lokaler Dev-Stack via docker-compose.dev.yml (npm run dev:docker etc.).
• autodeploy/multi/* – Build- und Deploy-Scripts (werden bei jedem Push mitsynchronisiert).
• create-nfs-volume.sh – nur bei articleblock / articleblock-full mit aktivierter NFS-Option.

Autodeploy – Wichtige Punkte

• MAIN_PROJECT_NAME in .env.autodeploy = Projektname aus dem Creator
• SSH_PRIVATE_KEY wird nur im klassischen Modus benötigt (GitHub-Clone auf Build-Server); im Workspace-Modus entfällt er
• Passwort-Auth über SSH_ASKPASS – kein sshpass erforderlich
• Autodeploy-Scripts (build_and_deploy_multi-repo.sh, multi_repo_build.sh, Dockerfiles) werden bei jedem Push auf den Build-Server aktualisiert
• Bundle-Modus: Wenn BUILD_SSH_DIR/bundles/ Bundles enthält, klont der Build-Server daraus – kein GitHub-Zugriff nötig
• Deploy-Server-Check via SSH-Hop durch Build-Server – nur Warnung bei fehlendem Verzeichnis, kein Abbruch

NFS-Option (nur articleblock / articleblock-full)

• Beim Generieren eines Projekts mit articleblock oder articleblock-full fragt der Creator "NFS hinzufügen?" (Default: ja)
• Bei aktiver NFS-Option setzt der Generator:
  • NFS_SERVER_ADDR=192.168.1.115 (Default) in .env.example und .env.autodeploy
  • Generiert create-nfs-volume.sh im Projekt-Root (idempotent – legt das Docker-Volume nfs_data_idml nur an, wenn es noch nicht existiert)
  • Bindet in docker-compose.yml das externe Volume nfs_data_idml als /data ein
• Alle Push-Skripte (push.sh, push.ps1, push.bat, workspace-push-node.mjs) kopieren create-nfs-volume.sh zusätzlich zu den Autodeploy-Dateien auf den Build-Server
• build_and_deploy_multi-repo.sh überträgt create-nfs-volume.sh auf den Deploy-Server und führt es vor docker compose up in einem Subshell ((cd … && ./create-nfs-volume.sh)) aus
• SSH zum Deploy-Server läuft key-only (BatchMode=yes)