landingpage-haus-schleusingen/AGENTS.md

Agent-Richtlinien für dieses Projekt

⚠️ WICHTIG: Pre-Commit Hooks sind Pflicht

Jeder Commit MUSS die Pre-Commit Lint-Checks durchlaufen. Niemals --no-verify verwenden!

Für AI-Agents (Claw etc.):

• Verwende ./scripts/safe-commit.sh "Nachricht" statt git commit -m "..."
• Das Script garantiert dass lint-staged läuft (PHP, HTML, CSS, JS, Prettier)
• Wenn ein Linter fehlschlägt: Fehler beheben, nicht überspringen!
• Niemals git commit --no-verify verwenden

Lint-Checks die laufen:

• PHP: php -l Syntax-Check (via scripts/lint-php.sh)
• HTML: htmlhint
• CSS: stylelint + prettier
• JS: eslint + prettier
• JSON/MD: prettier

---

Systemumgebung

• Betriebssystem: Linux – Befehle und Pfade sind Linux-kompatibel.

---

Projektübersicht

• Statische Landingpage für Haus Schleusingen
• Reines HTML, CSS und JavaScript (kein Framework, kein Build-Step)
• Ausgeliefert über einen Nginx-Docker-Container (nginx:alpine)
• Git-Repository: https://git.home.kies-media.de/greggy/landingpage-haus-schleusingen.git

Dateistruktur

Pfad	Beschreibung
public/index.php	Einstiegsseite (PHP-Entry-Point)
css/haus-schleusingen.css	Hauptstylesheet
js/haus-schleusingen.js	Haupt-JavaScript
js/masonry.pkgd.min.js	Masonry-Layout-Bibliothek (nicht bearbeiten)
fonts/fonts.css	Schriftart-Einbindungen
bilder/	Bildressourcen
nginx.conf	Nginx-Konfiguration
Dockerfile	Docker-Image-Definition (nginx:alpine)

---

Code-Qualität & Linting

Wichtig: Linting nach jeder Codeänderung durchführen

Führe nach jeder Codeänderung npm run lint aus, um die Codequalität zu garantieren.

Das Projekt verwendet folgende Tools:

Werkzeug	Zweck	Konfigurationsdatei	Befehl
HTMLHint	HTML-Linting	.htmlhintrc	npm run lint:html
Stylelint	CSS-Linting	.stylelintrc.json	npm run lint:css
ESLint	JavaScript-Linting	eslint.config.js	npm run lint:js
Prettier	Code-Formatierung	.prettierrc	npm run format
Husky	Git Hooks	.husky/pre-commit	–
lint-staged	Gesteuerte Dateien	package.json	–

Alle Linter auf einmal ausführen:

npm run lint

ESLint-Regeln (besonders beachten)

• no-unused-vars → Warnung (ungenutzte Variablen vermeiden)
• no-undef → Warnung (nur definierte Variablen verwenden)
• prettier/prettier → Fehler (Prettier-Formatierung ist Pflicht)
• Globale Variablen: browser und jquery sind verfügbar
• *.min.js-Dateien werden ignoriert (nicht linten/bearbeiten)

HTMLHint-Regeln

• Tag-Paarung Pflicht (tag-pair)
• Tags & Attribute in Kleinschreibung (tagname-lowercase, attr-lowercase)
• Doctype an erster Stelle (doctype-first)
• Eindeutige IDs (id-unique)
• alt-Attribut bei Bildern Pflicht (alt-require)
• <title> erforderlich (title-require)

---

Entwicklung

• Kein Build-Step erforderlich – statische Dateien
• Lokaler Entwicklungsserver: npx serve . oder VS Code Live Server
• Node.js ≥ 18, npm ≥ 9

Deployment

# Image bauen
docker build -t landingpage-haus-schleusingen .

# Container starten
docker run -d -p 8080:80 -v ${pwd}:/usr/share/nginx/html:ro landingpage-haus-schleusingen

Website erreichbar unter: http://localhost:8080

---

Wichtige Erkenntnisse

• jQuery wird als globale Bibliothek vorausgesetzt (in ESLint-Konfig definiert)
• Masonry (masonry.pkgd.min.js) wird für Layout-Zwecke eingesetzt – nicht bearbeiten
• Husky Pre-Commit-Hook führt automatisch lint-staged aus (kein manueller Schritt nötig beim Committen)
• Prettier-Formatierung ist verpflichtend – Code wird bei Commits automatisch formatiert
• Projekt ist commonjs-Typ (kein ESM in package.json)

---

Agent-Erkenntnisse (Systemumgebung & Tools)

Terminal & Encoding (Windows)

• PowerShell-Encoding-Probleme: Terminal-Ausgabe über run_terminal_command zeigt UTF-8-Zeichen (z. B. deutsche Umlaute) oft falsch an. Die Datei selbst ist korrekt. Immer mit read_file statt Terminal-Ausgabe prüfen.
• Backtick-Konflikt: PowerShell nutzt Backtick (``) als Escape-Zeichen. Markdown-Backticks in Here-Strings (@"..."@) führen zu Fehlern. Für Dateien mit Backticks stattdessen Node.js-Skripte verwenden.
• Zuverlässige Dateierstellung: Bei Inhalten mit Sonderzeichen (Umlaute, Backticks, Emojis) Node.js-Skripte (fs.writeFileSync) statt PowerShell-Befehle nutzen. Beispiel:

  const fs = require(`fs`);
  const B = String.fromCharCode(96); // Backtick vermeiden
  const lines = [`Zeile 1`, `Zeile 2`];
  fs.writeFileSync(`datei.md`, lines.join(`\n`), `utf8`);
  

Datei-Tools

• read_file-Anzeigegrenze: Lange Dateien werden in der Vorschau scheinbar abgeschnitten – die Datei selbst ist vollständig. Mit run_terminal_command und Get-Content -Tail N das Dateiende prüfen.
• create_new_file-Quoting: Inhalt darf nicht mit Anführungszeichen beginnen, da diese sonst als Teil des Inhalts übernommen werden. Immer die erstellte Datei verifizieren.
• single_find_and_replace: Exakte Stringübereinstimmung erforderlich. Zeilenumbrüche und Leerzeichen müssen exakt passen. Vor dem Ersetzen den Dateiinhalt mit read_file oder read_file_range prüfen.
• edit_existing_file-Encoding: Kann UTF-8-Zeichen (Umlaute, Sonderzeichen) beschädigen. Für Dateien mit Nicht-ASCII-Zeichen stattdessen Node.js-Skripte verwenden.

Workflow-Empfehlungen

1. Dateien lesen: Immer read_file oder read_file_range nutzen (nicht Terminal).
2. Dateien schreiben/ändern: edit_existing_file oder single_find_and_replace bevorzugen – aber Vorsicht bei Nicht-ASCII-Zeichen.
3. Komplexe Dateierstellung: Node.js-Skript über create_new_file + run_terminal_command ausführen, danach Hilfsskript löschen.
4. Terminal-Ausgabe: Nur für Dateigrößen, Git-Befehle und npm-Skripte nutzen – nicht zur Inhaltsprüfung von Textdateien.