From 54ccf400661e2be411b162b0ef7606c18f6fd7c7 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sat, 14 Feb 2026 20:45:34 +0100 Subject: [PATCH] updated TASK.md for debugging and build commands fix --- TASK.md | 340 ++++++++++++++++++-------------------------------------- 1 file changed, 109 insertions(+), 231 deletions(-) diff --git a/TASK.md b/TASK.md index 5f9f0c5..1fd3464 100644 --- a/TASK.md +++ b/TASK.md @@ -1,262 +1,140 @@ -# TASK.md — Fix: App Info Page Bugs +# TASK.md — Debug: App Info Page — YAML Parsing Failure > Read CLAUDE.md first for project context, workspace layout, and build instructions. -## Problems +## Problem -Two bugs on the `/apps/romm` info page: +The `/apps/romm` info page shows NO app info content (no tagline, no use cases, no optional +config form). More importantly, even basic metadata is missing: -### Bug 1: Logo SVG renders at native size (fills entire viewport) +- `~ RAM` badge shows no value (should be "300M") +- Category badge is empty (should be "media") +- Tagline `

` is empty -The `.app-info-logo` CSS sets `width: 80px; height: 80px` but the SVG logo image ignores these -constraints and renders at its intrinsic size (hundreds of pixels wide/tall), pushing all content -off-screen. +These fields have been in `.felhom.yml` since BEFORE the `app_info` section was added. If they're +empty, it means `LoadMetadata()` is silently failing and returning defaults. -**Root cause:** SVG images inside `` tags can ignore `width`/`height` CSS if the SVG file -itself has explicit `width`/`height` attributes or no `viewBox`. The `object-fit: contain` only -works when the container actually constrains the image. +## Root cause analysis -**Fix:** Make the logo constraint bulletproof. Update the `.app-info-logo` CSS in `templates.go`: +`LoadMetadata()` in `internal/stacks/metadata.go` swallows YAML parse errors: -```css -.app-info-logo { - width: 80px; - height: 80px; - min-width: 80px; - min-height: 80px; - max-width: 80px; - max-height: 80px; - border-radius: 12px; - object-fit: contain; - background: var(--bg-secondary); - padding: 10px; - flex-shrink: 0; - overflow: hidden; +```go +if err := yaml.Unmarshal(data, &meta); err != nil { + // Parse error — still return defaults <-- NO LOG OUTPUT! + dirName := filepath.Base(stackDir) + meta.DisplayName = toTitleCase(strings.ReplaceAll(dirName, "-", " ")) + meta.Slug = dirName + return meta } ``` -The key additions are `max-width`, `max-height`, and `overflow: hidden` which will force the -image to stay within bounds regardless of the SVG's intrinsic dimensions. +The YAML parse is failing for some reason, and the error is silently ignored. -### Bug 2: App info sections not rendering (use cases, first steps, optional config all missing) +## Step 1: Diagnose — check what the controller has in memory -The hero section renders (logo + badges) but the `app_info` content (tagline, use cases, first -steps, prerequisites, default creds, docs link) and `optional_config` (metadata provider fields) -are completely absent. The `

` is empty in the DOM. - -This means `HasAppInfo()` returns false and `HasOptionalConfig()` returns false, which means the -`.felhom.yml` file on the demo node does NOT contain the new `app_info` and `optional_config` -sections. - -**Diagnosis steps (run these first):** +Run this from your workstation to see the raw API data for romm: ```bash -# 1. Check if the stacks dir has the updated .felhom.yml -ssh kisfenyo@192.168.0.162 "cat /opt/docker/stacks/romm/.felhom.yml" +# Get a session first, then check the stack data +ssh kisfenyo@192.168.0.162 "curl -s http://localhost:8080/api/stacks" 2>/dev/null | head -200 ``` -If the output does NOT contain `app_info:` and `optional_config:`, the catalog sync hasn't -picked up the changes. Check: +Wait — API needs auth. Easier approach: add a temporary debug log. + +## Step 2: Add error logging to LoadMetadata + +In `controller/internal/stacks/metadata.go`, the `LoadMetadata` function currently swallows +parse errors silently. **Add logging** so we can see what's failing: + +```go +func LoadMetadata(stackDir string) Metadata { + meta := Metadata{} + + path := filepath.Join(stackDir, ".felhom.yml") + data, err := os.ReadFile(path) + if err != nil { + dirName := filepath.Base(stackDir) + meta.DisplayName = toTitleCase(strings.ReplaceAll(dirName, "-", " ")) + meta.Slug = dirName + meta.Category = "tools" + return meta + } + + if err := yaml.Unmarshal(data, &meta); err != nil { + // ADD THIS LOG LINE — this is critical for debugging + fmt.Fprintf(os.Stderr, "[ERROR] Failed to parse .felhom.yml in %s: %v\n", stackDir, err) + dirName := filepath.Base(stackDir) + meta.DisplayName = toTitleCase(strings.ReplaceAll(dirName, "-", " ")) + meta.Slug = dirName + return meta + } + + // ADD THIS DEBUG LINE — confirms successful parse + fmt.Fprintf(os.Stderr, "[DEBUG] Loaded metadata for %s: tagline=%q, useCases=%d, optConfig=%d\n", + filepath.Base(stackDir), meta.AppInfo.Tagline, len(meta.AppInfo.UseCases), len(meta.OptionalConfig)) + + // ... rest of function unchanged ... +``` + +You'll need to add `"fmt"` to the imports if not already there. + +## Step 3: Build, deploy, check logs + +Follow the CLAUDE.md build workflow. After deploying, immediately check logs: ```bash -# 2. Check if app-catalog repo was actually updated -cd /e/git/app-catalog-felhom.eu -git log --oneline -3 -cat templates/romm/.felhom.yml | grep -c "app_info" +ssh kisfenyo@192.168.0.162 "docker logs felhom-controller 2>&1 | grep -E 'ERROR.*felhom.yml|DEBUG.*Loaded metadata'" ``` -If the local repo doesn't have `app_info` in the romm `.felhom.yml`, the previous session -didn't update the app-catalog repo. You need to: +This will show either: +- `[ERROR] Failed to parse .felhom.yml in /opt/docker/stacks/romm: ` — tells us exactly what's wrong +- `[DEBUG] Loaded metadata for romm: tagline="Retró...", useCases=5, optConfig=1` — parsing works, problem is elsewhere -1. Update `E:\git\app-catalog-felhom.eu\templates\romm\.felhom.yml` with the full content - (see "RoMM .felhom.yml content" section below) -2. Update `E:\git\app-catalog-felhom.eu\templates\romm\docker-compose.yml` — add the missing - ScreenScraper + MobyGames env vars (see "RoMM docker-compose.yml changes" section below) -3. Commit and push the app-catalog repo -4. Trigger a catalog sync on the demo node (or wait 15 minutes) +## Step 4: Fix based on diagnosis -If the local repo DOES have `app_info` but the demo node doesn't, force a sync: +### If YAML parse error: + +The error message will tell us exactly what's wrong. Common causes: +- **Special Unicode characters** in quoted strings (Hungarian quotes `„"`, em-dash `—`) +- **Encoding issue** (BOM character at start of file) +- **Indentation** mismatch + +Fix the `.felhom.yml` content accordingly in the app-catalog repo, commit + push, trigger sync. + +### If parsing succeeds but data still missing: + +The problem is in how `ScanStacks()` stores/retrieves metadata. Check: +- Does `GetStacks()` return the full `Meta` field? +- Is there any code that creates a new `Metadata{}` after `LoadMetadata()`? + +## Step 5: After fixing, clean up debug logging + +Once the issue is resolved: +1. Keep the `[ERROR]` log line (it should have been there from the start — silent failures are bad) +2. Remove or gate the `[DEBUG]` line behind `isDebug()` check (or just remove it) +3. Build + deploy the final version + +## Build workflow fix for CLAUDE.md + +Also update the deploy command in CLAUDE.md. The `sed` approach for updating the image tag is +fragile — it matched the service name line too and broke the YAML last time. + +Replace Step 3 in CLAUDE.md with this safer approach: ```bash -# Trigger sync via API (need to login first to get session cookie) -# Or use the dashboard "Sablonok frissítése" button +# Deploy on demo node — use targeted sed that only matches the 'image:' line +ssh kisfenyo@192.168.0.162 "cd /opt/docker/felhom-controller && sudo docker pull gitea.dooplex.hu/admin/felhom-controller: && sudo sed -i 's|image: gitea.dooplex.hu/admin/felhom-controller:.*|image: gitea.dooplex.hu/admin/felhom-controller:|' docker-compose.yml && sudo docker compose up -d" ``` -**After the catalog sync, verify the fix:** +Key differences from previous command: +- `sudo` for both sed and docker compose (the directory is root-owned) +- sed pattern matches `image: gitea.dooplex.hu/admin/felhom-controller:.*` — only the image line, not the service name +- Single SSH command to avoid partial failures -```bash -ssh kisfenyo@192.168.0.162 "grep -c 'app_info' /opt/docker/stacks/romm/.felhom.yml" -# Should return 1 (meaning the app_info section exists) +Update the CLAUDE.md file with this corrected deploy command. -ssh kisfenyo@192.168.0.162 "grep -c 'optional_config' /opt/docker/stacks/romm/.felhom.yml" -# Should return 1 -``` +## Summary -Then reload `/apps/romm` in the browser — the info cards and optional config form should appear. - ---- - -## RoMM .felhom.yml content - -Replace `templates/romm/.felhom.yml` in the **app-catalog-felhom.eu** repo entirely with: - -```yaml -# ============================================================================= -# .felhom.yml — App metadata for felhom-controller -# ============================================================================= - -# --- Display info (shown on dashboard) --- -display_name: "RomM" -description: "Retró játékgyűjtemény kezelő" -category: "media" -subdomain: "arcade" -slug: "romm" - -# --- Resource hints (displayed on deploy screen) --- -resources: - mem_request: "300M" - mem_limit: "1024M" - pi_compatible: false - needs_hdd: true - -# --- Deploy fields (first deployment only) --- -deploy_fields: - - env_var: DOMAIN - label: "Domain" - type: domain - description: "A szerver domain neve" - locked_after_deploy: true - - - env_var: DB_PASSWORD - label: "Adatbázis jelszó" - type: secret - generate: "password:24" - locked_after_deploy: true - - - env_var: MYSQL_ROOT_PASSWORD - label: "MariaDB root jelszó" - type: secret - generate: "password:24" - locked_after_deploy: true - - - env_var: ROMM_AUTH_SECRET_KEY - label: "Hitelesítési titkosítási kulcs" - type: secret - generate: "hex:32" - locked_after_deploy: true - - - env_var: HDD_PATH - label: "Adattárolási útvonal" - type: path - required: true - placeholder: "/mnt/hdd_1" - description: "A külső merevlemez elérési útja, ahol a ROM-ok és borítóképek tárolódnak" - locked_after_deploy: true - -# --- App info (info page content) --- -app_info: - tagline: "Retró játékgyűjtemény kezelő, böngésző és lejátszó" - default_creds: "admin / admin" - docs_url: "https://github.com/rommapp/romm/wiki" - - use_cases: - - "Retró játékgyűjtemény rendszerezése és böngészése webes felületen" - - "Játékok metaadatainak automatikus letöltése — borítók, leírások, értékelések" - - "Platformonkénti szűrés és keresés a teljes gyűjteményben" - - "ROM fájlok webes feltöltése és letöltése" - - "Többfelhasználós hozzáférés a háztartás tagjai számára" - - first_steps: - - "Nyisd meg az arcade.DOMAIN címet a böngészőben" - - "Jelentkezz be az alapértelmezett admin / admin fiókkal" - - "Változtasd meg azonnal a jelszót a Settings menüben" - - "Töltsd fel a ROM fájlokat a library mappába (platform/játéknév struktúrával)" - - "Indíts egy Scan-t a bal oldali menüben a ROM-ok beolvasásához" - - "Opcionális: állíts be metaadat-szolgáltatókat a borítóképek és leírások automatikus letöltéséhez (lásd lent)" - - prerequisites: - - "Külső HDD szükséges a ROM fájlok és borítóképek tárolásához" - - "Legalább 1 GB szabad RAM ajánlott (MariaDB + Redis + RomM)" - - "ROM fájlok platform mappákba rendezve (pl. library/gba/, library/snes/)" - -# --- Optional config (configurable before or after deployment) --- -optional_config: - - group: "Metaadat-szolgáltatók" - description: "Játékok borítóinak, leírásainak és értékeléseinek automatikus letöltéséhez. Legalább az IGDB beállítása ajánlott. Mindegyik ingyenesen használható regisztráció után." - fields: - - env_var: IGDB_CLIENT_ID - label: "IGDB Client ID" - type: text - help_url: "https://api-docs.igdb.com/#getting-started" - help_text: "1) Regisztrálj / jelentkezz be a Twitch fejlesztői portálon (dev.twitch.tv). 2) Hozz létre egy új alkalmazást (bármilyen névvel). 3) Másold be a Client ID-t." - - - env_var: IGDB_CLIENT_SECRET - label: "IGDB Client Secret" - type: secret_input - help_text: "A Twitch alkalmazásod Client Secret-je (a „New Secret" gombbal generálhatod)." - - - env_var: STEAMGRIDDB_API_KEY - label: "SteamGridDB API Key" - type: text - help_url: "https://www.steamgriddb.com/profile/preferences/api" - help_text: "Regisztrálj a SteamGridDB oldalon, majd a Preferences → API fül alatt kattints a „Generate API key" gombra." - - - env_var: SCREENSCRAPER_USER - label: "ScreenScraper felhasználónév" - type: text - help_url: "https://www.screenscraper.fr/" - help_text: "Regisztrálj a screenscraper.fr oldalon. A felhasználóneved lesz az API felhasználónév." - - - env_var: SCREENSCRAPER_PASSWORD - label: "ScreenScraper jelszó" - type: secret_input - help_text: "A screenscraper.fr fiókod jelszava." - - - env_var: MOBYGAMES_API_KEY - label: "MobyGames API Key" - type: text - help_url: "https://www.mobygames.com/info/api/" - help_text: "Regisztrálj a MobyGames oldalon, majd az API oldalon igényelj kulcsot. Részletes játékinformációkat és krediteket biztosít." -``` - ---- - -## RoMM docker-compose.yml changes - -In `E:\git\app-catalog-felhom.eu\templates\romm\docker-compose.yml`, in the romm service's -`environment:` section, after the existing `STEAMGRIDDB_API_KEY` line, add these three lines: - -```yaml - - SCREENSCRAPER_USER=${SCREENSCRAPER_USER:-} - - SCREENSCRAPER_PASSWORD=${SCREENSCRAPER_PASSWORD:-} - - MOBYGAMES_API_KEY=${MOBYGAMES_API_KEY:-} -``` - ---- - -## Implementation order - -1. **Diagnose Bug 2 first** — run the SSH commands above to check if `.felhom.yml` on the node - has the `app_info` section. This tells us whether the catalog update was missed or sync failed. -2. **Fix Bug 1** — update `.app-info-logo` CSS in `controller/internal/web/templates.go` -3. **Fix Bug 2** — if the app-catalog wasn't updated: - a. Update `templates/romm/.felhom.yml` in `E:\git\app-catalog-felhom.eu\` - b. Update `templates/romm/docker-compose.yml` in `E:\git\app-catalog-felhom.eu\` - c. Commit + push the app-catalog repo: - ```bash - cd /e/git/app-catalog-felhom.eu - git add -A && git commit -m "romm: add app_info + optional_config metadata, add ScreenScraper + MobyGames env vars" && git push - ``` -4. **Build + deploy** the controller with the CSS fix (follow CLAUDE.md build workflow) -5. **Trigger catalog sync** — either wait 15m or use the dashboard "Sablonok frissítése" button -6. **Verify** — reload `/apps/romm` and confirm: - - [ ] Logo is 80x80, not filling the screen - - [ ] Tagline text visible: "Retró játékgyűjtemény kezelő, böngésző és lejátszó" - - [ ] "Mire használható?" card with 5 use cases - - [ ] "Első lépések" card with 6 steps - - [ ] "Előfeltételek" card with 3 items - - [ ] "Alapértelmezett belépés" card showing "admin / admin" - - [ ] "Dokumentáció" card with link to RomM wiki - - [ ] "Opcionális beállítások" section with 6 metadata provider fields - - [ ] "Mentés" button on optional config form -7. **Update CONTEXT.md** with the fixes applied \ No newline at end of file +The core issue is that `LoadMetadata()` silently swallows YAML parse errors. Even if the fix +turns out to be a simple YAML syntax issue, the error logging should be added permanently — +silent failures make debugging impossible. \ No newline at end of file