From 3449042051e4fdcfd7f087c4486eac456d65edb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Lohrer?= Date: Tue, 28 Apr 2026 09:29:36 +0200 Subject: [PATCH] docs: top-level-doku auf prerender-snapshot-stand MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aus dem code-review der etappe (2026-04-28): - CLAUDE.md: snapshot/-verzeichnis in hauptarbeitsbereiche-tabelle ergaenzt; neue stolperfalle "snapshot-output muss vor npm run build da sein" eingefuegt. - STATUS.md: kurzfassung um den prerender-stand erweitert; repo-baum zeigt snapshot/; erledigt-eintrag mit den sechs etappen. - HANDOFF.md: stolperfalle "snapshot vor build" am anfang der liste — haeufigster fallstrick fuer naechste session. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 15 ++++++++++++++- docs/HANDOFF.md | 8 ++++++++ docs/STATUS.md | 33 ++++++++++++++++++++++++++++----- 3 files changed, 50 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index de57275..a291619 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -79,7 +79,17 @@ mit `../content/posts/...`. Git-Diff liefert aber repo-root-relative Pfade (`content/posts/...`). `changedPostDirs` normalisiert beides — wenn `posts=0` obwohl Änderungen vorliegen, ist das der Hotspot. -### 5. Publish-Pipeline erwartet `content/posts///` +### 5. Snapshot-Output muss vor `npm run build` da sein + +SvelteKit prerendert `[...slug]/+page.{ts,svelte}` aus +`snapshot/output/`-JSONs (`index.json` + `posts/.json`). Lokal +buildst du nicht direkt mit `npm run build`, sondern via +`./scripts/deploy-svelte.sh` — das ruft vorher `deno task snapshot` +auf. Wer `cd app && npm run build` direkt nach dem Clone macht, ohne +vorher `cd snapshot && deno task snapshot` auszuführen, scheitert +mit `ENOENT snapshot/output/index.json`. + +### 6. Publish-Pipeline erwartet `content/posts///` Die Zwei-Ebenen-Struktur ist Teil der Traversierung. Wer einen Post versehentlich in `content/posts//` (ohne Sprach-Ordner) anlegt, @@ -96,6 +106,9 @@ wird von der Pipeline ignoriert. | `app/src/routes/` | SvelteKit-Routen (Layout, Home, Archiv, Post, Impressum) | | `publish/src/` | Deno-Publish-Pipeline (Deno-Tasks in `publish/deno.jsonc`) | | `publish/tests/` | Deno-Tests für die Pipeline | +| `snapshot/src/` | Deno-Snapshot-Tool (Relays → JSON für Prerender) | +| `snapshot/tests/` | Deno-Tests für den Snapshot | +| `snapshot/output/` | (gitignored) build-zeit-JSON, wird vom SvelteKit-Prerender konsumiert | | `docs/superpowers/specs/` | Produktdesigns, Konventionen | | `docs/superpowers/plans/archive/` | Umgesetzte Implementierungspläne (Geschichte) | | `scripts/deploy-svelte.sh` | FTPS-Deploy | diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 8cb3d3a..a89e513 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -221,6 +221,14 @@ cd publish && deno task test # tests ## Bekannte Stolperfallen +- **Snapshot vor Build:** `app/build` braucht zur Build-Zeit + `snapshot/output/index.json` und `snapshot/output/posts/.json`. + `./scripts/deploy-svelte.sh` zieht den Snapshot automatisch vor dem + Build. Wer `cd app && npm run build` direkt aufruft, ohne vorher + `cd snapshot && deno task snapshot` auszuführen, scheitert mit + ENOENT auf `index.json`. Frische Posts erscheinen erst nach einem + Snapshot-Re-Run, weil die Detail-Route ausschließlich aus dem + Snapshot rendert (kein Runtime-Relay-Fetch mehr). - **Amber-Bunker:** bei neuer Bunker-URL müssen die zwei Permissions (`get_public_key`, `sign_event`) in Amber auf „Allow + Always" gesetzt werden, bevor Publish-Requests verarbeitet werden. Siehe diff --git a/docs/STATUS.md b/docs/STATUS.md index 71d2975..acc6f0a 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -3,7 +3,7 @@ > **Rolle dieses Dokuments:** Logbuch — aktueller Stand und Erledigt-Chronologie. > Konventionen und Workflows stehen in [`HANDOFF.md`](HANDOFF.md). -**Stand:** 2026-04-21 (Mehrsprachigkeit live) +**Stand:** 2026-04-28 (Prerender-Snapshot live auf svelte-subdomain) ## Kurzfassung @@ -12,6 +12,14 @@ signierten Nostr-Events (NIP-23, `kind:30023`) auf 5 Public-Relays rendert. Bilder liegen content-addressed auf 2 Blossom-Servern. Die Hugo-basierte Altseite ist als `hugo-archive`-Branch eingefroren. +**Seit 2026-04-28 prerender-snapshot:** Post-Detailseiten werden zur +Build-Zeit prerendered, mit vollen OG-/Twitter-/JSON-LD-Tags. Ein Deno- +Tool (`snapshot/`) liest die Events von den Relays und schreibt sie als +JSON-Artefakte; SvelteKit baut daraus `/index.html` mit korrekten +Meta-Tags. Crawler und Social-Media-Vorschauen sehen jetzt echte Titel, +Beschreibungen, Cover-Bilder. Live verifiziert auf `svelte.joerg-lohrer.de`, +prod-merge ausstehend. + **Seit 2026-04-21 multilingual:** UI-Chrome (Menü, Footer, Post-Meta) in Deutsch und Englisch via `svelte-i18n`, mit Browser-Locale-Default, `localStorage`-Persistenz und Header-Sprachswitcher. Inhalte pro Sprache @@ -59,9 +67,10 @@ joerglohrerde/ ├── content/impressum.md # Statisches Impressum (wird von SPA geladen) ├── app/ │ ├── src/lib/i18n/ # svelte-i18n + activeLocale-Store + Messages -│ ├── src/lib/nostr/ # Relay-Loader, Translations-Resolving -│ └── src/lib/components/ # u. a. LanguageSwitcher, LanguageAvailability +│ ├── src/lib/nostr/ # Relay-Loader (Listen, Replies, Reactions, Profile) +│ └── src/lib/components/ # u. a. LanguageSwitcher, Reactions, ReplyComposer ├── publish/ # Deno-Publish-Pipeline (Blossom + Nostr) +├── snapshot/ # Deno-Snapshot-Tool (Relays → JSON für Prerender) ├── preview/spa-mini/ # Vanilla-HTML-Mini-Spike (historisch) ├── scripts/ │ └── deploy-svelte.sh # FTPS-Deploy, Targets: svelte/staging/prod @@ -73,9 +82,9 @@ joerglohrerde/ │ ├── wiki-draft-nostr-image-metadata.md │ ├── github-ci-setup.md │ └── superpowers/ -│ ├── specs/ # SPA, Publish-Pipeline, Bild-Metadaten, Multilingual, Prerender (Entwurf) +│ ├── specs/ # SPA, Publish-Pipeline, Bild-Metadaten, Multilingual, Prerender, Docs-Cleanup │ └── plans/ -│ └── archive/ # Umgesetzte Pläne (Geschichte) + eingefrorener Prerender-Plan +│ └── archive/ # Umgesetzte Pläne (Geschichte) + Prerender-Plan (durch 2026-04-28 ersetzt) ├── .github/workflows/ # publish.yml (Forgejo→GitHub Push-Mirror-Trigger) ├── .claude/ │ ├── skills/ # Repo-spezifischer Claude-Skill @@ -117,6 +126,20 @@ Nach Priorität: ## Erledigt (chronologisch seit 2026-04-15) +- ✅ **Prerender-Snapshot (2026-04-28)** — Post-Detailseiten werden zur + Build-Zeit prerendered, nicht mehr live aus Relays. Sechs Etappen: + - `renderMarkdown` auf `isomorphic-dompurify` (node-fähig). + - Neues `snapshot/`-Modul (Deno) mit 32 Tests, liest Events von + Relays und schreibt JSON-Artefakte (NIP-09-aware, Plausibilitäts- + Checks, Cover-Probe, Cache mit akkumulierten deletedCoords). + - GitHub-Action zieht Snapshot nach jedem Publish als Artifact. + - SvelteKit-Detail-Route auf `prerender=true` mit `` für + OG/Twitter/JSON-LD/hreflang. `` + `og:image:width/height` + pro Post korrekt gesetzt; `x-default` zeigt auf DE-Slug. + - Runtime-Relay-Fetch der Detail-Route entfernt. + - Deploy-Skript ruft Snapshot vor SvelteKit-Build auf. + - Toten Code aus Pre-Prerender-Ära entfernt (PostView, LanguageAvailability, + loadPost, loadTranslations, translations.ts). - ✅ Content-Migration: alle 18 Posts haben strukturierte `images:`-Liste im Frontmatter (91 Bilder, mit Alt-Text, Lizenz, Autor:innen, ggf. Caption und Modifications).