docs: restructure docs/ into guides/ reference/ working/ research/

2026-06-21 12:36:35 +02:00
parent 647f76333d
commit 28008da922
35 changed files with 0 additions and 0 deletions
@@ -0,0 +1,204 @@
+# Bugs & Fixes
+
+Backlog of confirmed bugs with root cause analysis and implementation spec for the fix.
+
+---
+
+## BUG-001 — New entry not visible after form submission
+
+**Status:** fixed 2026-06-18  
+**Reported:** 2026-06-18  
+
+### Symptom
+
+After submitting a new post via `/post`, the entry page file is created correctly on disk but does not appear in the `/trips/<active_trip>/dailies` feed or in the Grav Admin panel until the cache is manually flushed.
+
+### Root cause
+
+Grav's page-tree cache (`cache/doctrine/`) is not invalidated when `add-page-by-form` writes a new page to disk. The tracker template uses `page.children`, which Grav serves from cache — so the new child page is invisible until the cache is cleared.
+
+### Workaround (manual)
+
+Run in terminal after each submission:
+
+```bash
+docker exec intotheeast_grav bash -c "cd /var/www/html && php bin/grav clearcache"
+```
+
+### Fix spec
+
+Wire cache-clear into the form process so it happens automatically on every successful submission.
+
+**Approach — custom Grav plugin event hook:**
+
+1. Create a small plugin `user/plugins/cache-on-save/` with one event listener:
+   - Listen on `onFormProcessed`
+   - When the form name is `new-entry`, call `$this->grav['cache']->deleteAll()` (note: `clear()` does not exist on `Grav\Common\Cache` in Grav 1.7)
+2. Enable the plugin in `user/config/plugins/cache-on-save.yaml`
+
+This is the cleanest approach: it fires exactly once per successful submission, requires no changes to `post-form.md`, and works for any future forms too.
+
+**Alternative — disable page cache entirely:**
+
+Set `cache: { enabled: false }` in `system.yaml`. Simpler but degrades frontend performance; not recommended for production.
+
+### Files to create/modify
+
+| File | Change |
+|------|--------|
+| `user/plugins/cache-on-save/cache-on-save.php` | New plugin, ~30 lines |
+| `user/plugins/cache-on-save/cache-on-save.yaml` | Plugin manifest, enabled: true |
+| `user/config/plugins/cache-on-save.yaml` | Runtime config, enabled: true |
+
+### Acceptance criteria
+
+1. Submit a new post via `/post`
+2. Navigate to `/trips/<active_trip>/dailies` — the new entry is visible immediately, no manual cache flush needed
+3. Grav Admin also shows the new page immediately
+
+---
+
+## BUG-002 — Stale Twig cache after theme file changes
+
+**Status:** fixed 2026-06-18  
+**Reported:** 2026-06-18  
+
+### Symptom
+
+After theme template files are added or modified (e.g., creating `partials/base.html.twig`), Grav's Twig compiled-template cache still holds the old compiled version. Pages that extend the changed file throw 500 errors like "Template partials/base.html.twig is not defined" even though the file exists on disk.
+
+### Root cause
+
+Grav caches compiled Twig templates in `cache/twig/`. When a new file is added, existing templates that reference it don't know to recompile — their cache entries are still valid from their own mtime perspective.
+
+### Workaround (manual)
+
+Run after any theme file is added or changed:
+
+```bash
+docker exec intotheeast_grav bash -c "cd /var/www/html && php bin/grav clearcache"
+```
+
+### Fix spec
+
+Disable Twig template caching in development via `user/config/system.yaml`:
+
+```yaml
+twig:
+  cache: false
+```
+
+Acceptable for a single-user dev setup — eliminates both BUG-001's side-effect and this bug entirely. Performance cost is negligible at one-user scale. On production, leave Twig cache enabled (it's fine there because template files don't change at runtime).
+
+**Files to change:**
+
+| File | Change |
+|------|--------|
+| `user/config/system.yaml` | Add `twig: { cache: false }` under development section |
+
+### Acceptance criteria
+
+1. Add a new theme template file
+2. Reload any page — no 500 error, template works immediately without manual cache flush
+
+---
+
+## BUG-003 — One post per day limit; silent failure on duplicate date
+
+**Status:** fixed 2026-06-18
+**Reported:** 2026-06-18
+
+### Symptom
+
+Submitting a second post with the same date as an existing entry shows "Entry posted successfully!" but creates no file. The user's post is silently discarded.
+
+### Root cause
+
+The `add-page-by-form` plugin built the page slug from date only (`Y-m-d`), producing folder names like `2026-06-18.entry`. With `overwrite_mode: false`, if that folder already exists the plugin skips page creation but does not abort — the `message` process step runs regardless, showing a false success.
+
+### Fix
+
+Change the slug template in `user/pages/02.post/post-form.md` to include time and title:
+
+```twig
+{{ form.value.date|date('Y-m-d-Hi') }}-{{ form.value.title|lower|regex_replace('/[^a-z0-9]+/', '-')|trim('-') }}
+```
+
+Example: title "Arrived in Tokyo" at 14:30 on 2026-06-18 → `2026-06-18-1430-arrived-in-tokyo`
+
+The slug is locked at creation time. Renaming the title afterwards does not change the URL.
+
+### Acceptance criteria
+
+1. Submit two posts on the same day with different times or titles — both appear in `/trips/<active_trip>/dailies` as separate entries
+2. Renaming a post's title in the frontmatter does not break its URL
+
+---
+
+## BUG-004 — Admin2 shows empty dashboard after Grav 2.0 upgrade
+
+**Status:** fixed 2026-06-19
+
+### Symptom
+
+After installing Grav 2.0 + Admin2, logging in shows an empty dashboard with no sidebar navigation (only a Settings item visible). Pages and content are not accessible.
+
+### Root causes (three separate issues)
+
+**A) Wrong user account type.** `system.yaml` had `accounts.type: regular` (old file-based system). Admin2's API plugin uses the Flex user collection to look up accounts. With `regular`, the API saw zero users and entered setup-wizard mode.
+
+**B) Wrong pages type.** `system.yaml` had `pages.type: regular`. Admin2's pages API requires `pages.type: flex` to serve the page tree.
+
+**C) Missing `api.*` permissions on user account.** Grav 2.0 Admin2 uses a new `api.*` permission namespace (`api.super`, `api.access`, etc.) instead of the old `admin.super`. A user with only `access.admin.super: true` appears as a non-admin to Admin2.
+
+### Fix
+
+In `user/config/system.yaml`:
+```yaml
+accounts:
+  type: flex
+pages:
+  type: flex
+```
+
+In `user/accounts/<username>.yaml`:
+```yaml
+access:
+  admin:
+    login: true
+    super: true      # keep for backward compat
+  api:
+    super: true      # required by Admin2
+    access: true     # required by Admin2
+```
+
+### Notes
+
+- `api.super: true` causes Admin2 to grant all sub-permissions automatically (`api.pages`, `api.config`, etc.)
+- JWT secret in `user/plugins/api/api.yaml` can stay empty — HMAC-SHA256 works with an empty key locally; production generates its own secure secret
+- The old `admin` plugin must be disabled (`enabled: false`) to avoid route conflict with `admin2`
+
+---
+
+## BUG-005 — PHP session fails after Grav 2.0 container upgrade
+
+**Status:** fixed 2026-06-19
+
+### Symptom
+
+After replacing Grav core files inside the container, all pages return a CRITICAL error in `logs/grav.log`: `Failed to start session: session_start(): Failed to read session data: files (path: )`. Site is inaccessible.
+
+### Root cause
+
+The `getgrav/grav` Docker image's PHP configuration does not set `session.save_path`. Grav 1.7 worked because the image's default PHP config included it; the updated image layer did not.
+
+### Fix
+
+Add to `php/php-local.ini`:
+```ini
+session.save_path = /tmp
+```
+
+Restart the container to pick up the change. This file is bind-mounted into the container so no image rebuild is needed.
+
+---