From d7d5a1e25dc89b488600fe84f00f898fac9fc19e Mon Sep 17 00:00:00 2001 From: devRaGonSa Date: Fri, 20 Mar 2026 20:31:39 +0100 Subject: [PATCH] chore: clean repo runtime artifacts --- .gitignore | 7 ++ ...erver-status-periodic-query-and-display.md | 96 ++++++++++++++++++ ...-repo-hygiene-and-dev-artifacts-cleanup.md | 87 ++++++++++++++++ ai/worker.lock | 1 - backend/app/config.py | 2 +- backend/data/.gitkeep | 1 + backend/data/hll_vietnam_dev.sqlite3 | Bin 40960 -> 0 bytes 7 files changed, 192 insertions(+), 2 deletions(-) create mode 100644 ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md create mode 100644 ai/tasks/done/TASK-025-repo-hygiene-and-dev-artifacts-cleanup.md delete mode 100644 ai/worker.lock create mode 100644 backend/data/.gitkeep delete mode 100644 backend/data/hll_vietnam_dev.sqlite3 diff --git a/.gitignore b/.gitignore index 65a29bc..628f4b6 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,10 @@ dist/ build/ .DS_Store Thumbs.db + +# Local AI worker/runtime artifacts +ai/worker.lock + +# Local backend runtime data +backend/data/*.sqlite3 +!backend/data/.gitkeep diff --git a/ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md b/ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md new file mode 100644 index 0000000..27ccaef --- /dev/null +++ b/ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md @@ -0,0 +1,96 @@ +# TASK-021-server-status-periodic-query-and-display + +## Goal +Implementar una base funcional para consultar periódicamente el estado de los servidores y mostrar esos datos en la página, realizando snapshots de datos cada 2 minutos, sin usar capturas de imagen ni elementos manuales equivalentes. + +## Context +Queda descartada cualquier idea de “captura manual” o de imagen estática para representar el estado de los servidores. Lo que se necesita es mostrar en la web la situación actual de los servidores mediante consultas de datos reales o semirrealistas desde backend. En esta fase, la web debe evolucionar hacia un modelo donde el backend consulta periódicamente la información de servidores, conserva el último snapshot útil y el frontend lo muestra de forma clara. + +## Steps +1. Revisar el endpoint actual `GET /api/servers` y su implementación placeholder. +2. Revisar cómo se muestra actualmente el bloque de servidores en la landing. +3. Diseñar e implementar una base de consulta periódica de datos de servidores con una frecuencia objetivo de 2 minutos. +4. Hacer que el backend obtenga y conserve snapshots de datos con los campos necesarios para la UI. Incluir al menos: + - nombre del servidor + - estado online/offline + - jugadores actuales + - capacidad máxima + - mapa actual si está disponible + - región o etiqueta útil si existe + - timestamp real del último snapshot de datos +5. Dejar claro en la implementación y en la UI que se trata de datos de estado de servidores, no de capturas de imagen. +6. Hacer que `GET /api/servers` devuelva el último snapshot útil con una estructura estable y preparada para frontend. +7. Ajustar el frontend para mostrar esos datos de forma clara en la landing. +8. Si el backend no puede obtener datos nuevos temporalmente, mantener el último snapshot válido o un fallback coherente sin romper la página. +9. Mostrar en la UI una referencia honesta del momento de actualización basada en datos reales del snapshot, no en texto ficticio. +10. Mantener el alcance razonable: consultas periódicas y presentación de datos, sin abrir todavía automatizaciones más complejas de observabilidad o infraestructura. + +## Files to Read First +- AGENTS.md +- ai/repo-context.md +- ai/architecture-index.md +- docs/frontend-backend-contract.md +- docs/discord-and-server-data-plan.md +- docs/current-hll-servers-source-plan.md +- backend/README.md +- backend/app/__init__.py +- backend/app/main.py +- backend/app/routes.py +- backend/app/payloads.py +- backend/app/config.py +- frontend/index.html +- frontend/assets/js/main.js +- frontend/assets/css/styles.css + +## Expected Files to Modify +- backend/app/main.py +- backend/app/routes.py +- backend/app/payloads.py +- backend/app/config.py +- opcionalmente uno o más archivos nuevos de servicio dentro de `backend/app/`, por ejemplo: + - backend/app/server_status_service.py + - backend/app/server_queries.py +- frontend/index.html +- frontend/assets/js/main.js +- frontend/assets/css/styles.css +- backend/README.md +- opcionalmente documentación técnica si fuera necesario alinear el comportamiento real + +## Constraints +- No usar capturas de imagen para representar el estado de servidores. +- No introducir texto temporal ficticio. +- No consultar fuentes externas directamente desde frontend. +- Mantener la arquitectura frontend → backend → fuente de datos. +- No romper el fallback actual si no hay datos disponibles. +- No hacer cambios destructivos. +- Mantener la solución clara, trazable y coherente con la fase del proyecto. + +## Validation +- Existe una base de consulta periódica con objetivo de refresco cada 2 minutos. +- `GET /api/servers` devuelve un snapshot de datos de servidores con timestamp real del snapshot. +- La landing muestra esos datos en lugar de una “captura” manual o ficticia. +- Si falla la actualización, la web no se rompe. +- La UI muestra de forma honesta la actualización real del estado de servidores. +- No se introducen capturas de imagen como solución del problema. + +## Change Budget +- Preferir menos de 8 archivos modificados o creados. +- Preferir menos de 320 líneas cambiadas. + +## Outcome +- `backend/app/payloads.py` hace que `GET /api/servers` devuelva un snapshot coherente preparado para frontend: prioriza el ultimo snapshot A2S real persistido cuando existe y, si no existe ninguno, responde un respaldo controlado con `last_snapshot_at`. +- `backend/app/config.py` alinea la frecuencia objetivo de refresco local a `120` segundos. +- `frontend/assets/js/main.js` deja de depender de una segunda llamada a `/api/servers/latest` para el bloque principal y pinta directamente el snapshot devuelto por `/api/servers`, mostrando un estado honesto con timestamp real del snapshot. +- `frontend/index.html` ajusta el polling por defecto a `120000` ms y aclara que el bloque muestra snapshots de estado consultados desde backend. +- `backend/README.md` documenta el nuevo comportamiento de `/api/servers` y el intervalo de `120` segundos. + +## Validation Result +- Validado con `python -m py_compile backend/app/config.py backend/app/payloads.py backend/app/routes.py backend/app/main.py`. +- Validado con `node --check frontend/assets/js/main.js`. +- Validado con `python -m app.collector --source controlled`, que persistio un snapshot controlado en `backend/data/hll_vietnam_dev.sqlite3`. +- Validado inspeccionando `build_servers_payload()` desde Python para confirmar que `/api/servers` devuelve `last_snapshot_at` e `items` listos para frontend. +- Revisado en diff: la task queda limitada a `backend/README.md`, `backend/app/config.py`, `backend/app/payloads.py`, `frontend/assets/js/main.js`, `frontend/index.html`, este archivo de task y la actualizacion de `backend/data/hll_vietnam_dev.sqlite3` causada por la validacion persistente. + +## Decision Notes +- Se reutilizo la infraestructura de snapshots ya existente en lugar de introducir otro scheduler o un segundo endpoint principal para el estado visible en landing. +- `/api/servers` devuelve un unico conjunto coherente de items para evitar mezclar timestamps de fallback con tarjetas reales A2S en la UI. diff --git a/ai/tasks/done/TASK-025-repo-hygiene-and-dev-artifacts-cleanup.md b/ai/tasks/done/TASK-025-repo-hygiene-and-dev-artifacts-cleanup.md new file mode 100644 index 0000000..501af6b --- /dev/null +++ b/ai/tasks/done/TASK-025-repo-hygiene-and-dev-artifacts-cleanup.md @@ -0,0 +1,87 @@ +# TASK-025-repo-hygiene-and-dev-artifacts-cleanup + +## Goal +Dejar el repositorio HLL Vietnam en un estado mas limpio y consistente eliminando o regularizando artefactos locales de desarrollo, ficheros de lock y residuos de workflow que no deberian quedar como ruido permanente en el worktree. + +## Context +Despues de varias tasks ejecutadas por el workflow, siguen apareciendo residuos locales o inconsistencias de higiene del repositorio, entre ellos: +- `ai/worker.lock` +- `backend/data/hll_vietnam_dev.sqlite3` +- `ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md` como untracked o no regularizado +- posibles cambios locales en `backend/app/config.py` + +Estos elementos no forman parte directa del valor de producto visible, pero si afectan a la salud del repositorio, al flujo del worker y a la claridad del estado git. Hace falta una pasada de limpieza controlada para dejar reglas claras sobre que debe versionarse y que debe considerarse artefacto local de desarrollo. + +## Steps +1. Revisar el estado actual del repositorio y confirmar que archivos siguen quedando como ruido local o inconsistencias. +2. Analizar especificamente: + - `ai/worker.lock` + - `backend/data/hll_vietnam_dev.sqlite3` + - `ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md` + - `backend/app/config.py` +3. Determinar para cada uno de ellos si debe: + - versionarse + - ignorarse + - regenerarse localmente + - moverse o regularizarse +4. Ajustar `.gitignore` u otros mecanismos de higiene si hace falta. +5. Asegurar que los artefactos locales de desarrollo no sigan ensuciando el worktree innecesariamente. +6. Regularizar el estado de la task `TASK-021` si quedo fuera del flujo esperado. +7. Documentar de forma minima, si hace falta, el tratamiento esperado de snapshots persistidos, locks locales y otros artefactos de runtime. +8. No tocar logica funcional de producto salvo que sea estrictamente necesario para dejar el repo coherente. +9. Al completar la implementacion: + - dejar el repositorio consistente + - hacer commit + - hacer push al remoto si el entorno lo permite + +## Files to Read First +- AGENTS.md +- .gitignore +- ai/README.md +- ai/orchestrator/README.md +- backend/README.md +- backend/app/config.py +- cualquier documentacion existente sobre snapshots o runtime local +- salida actual de `git status` + +## Expected Files to Modify +- .gitignore +- backend/README.md +- opcionalmente ai/README.md o documentacion minima si hace falta aclarar el tratamiento de artefactos locales +- opcionalmente regularizacion de archivos en `ai/tasks/done/` +- opcionalmente eliminacion o exclusion de artefactos locales no deseados + +## Constraints +- No romper el workflow actual del proyecto. +- No eliminar informacion util sin justificarlo. +- No tocar frontend salvo que fuera completamente imprescindible. +- No introducir cambios funcionales de producto. +- No hacer cambios destructivos fuera del objetivo de higiene del repo. +- Mantener el resultado claro, pequeno y seguro. + +## Validation +- El worktree queda sensiblemente mas limpio. +- Los artefactos de desarrollo local quedan tratados de forma explicita. +- `ai/worker.lock` no queda como ruido permanente si no debe versionarse. +- El tratamiento de `backend/data/hll_vietnam_dev.sqlite3` queda resuelto. +- `TASK-021` queda regularizada si estaba fuera del flujo. +- Los cambios quedan committeados y se hace push al remoto si el entorno lo permite. + +## Change Budget +- Preferir menos de 6 archivos modificados. +- Preferir menos de 180 lineas cambiadas. + +## Outcome +- `.gitignore` pasa a tratar `ai/worker.lock` y `backend/data/*.sqlite3` como artefactos locales de runtime en lugar de ruido permanente versionado. +- `backend/data/.gitkeep` mantiene el directorio de datos en el repositorio sin forzar que la base SQLite de desarrollo quede commiteada. +- `ai/tasks/done/TASK-021-server-status-periodic-query-and-display.md` queda regularizada dentro del historial versionado de tasks completadas. +- El cambio pendiente de `backend/app/config.py` queda absorbido como parte de la regularizacion de `TASK-021`, en lugar de seguir apareciendo como residuo suelto. + +## Validation Result +- Revisado `git status --short` para confirmar que el ruido original del worktree quedaba centrado en `ai/worker.lock`, `backend/data/hll_vietnam_dev.sqlite3`, `backend/app/config.py` y la task `TASK-021`. +- Revisadas las referencias de runtime en `scripts/codex-runner.ps1`, `backend/app/config.py` y `backend/README.md` para confirmar que el lock y la SQLite son artefactos regenerables de desarrollo local. +- Validacion final prevista: `git diff --name-only` debe reflejar solo la higiene de ignores, la regularizacion de archivos versionados y la task cerrada. + +## Decision Notes +- `ai/worker.lock` se trata como lock efimero del runner local y no aporta valor historico en git. +- `backend/data/hll_vietnam_dev.sqlite3` se mantiene como persistencia local regenerable; el contrato util esta en codigo y documentacion, no en una base SQLite concreta del worktree. diff --git a/ai/worker.lock b/ai/worker.lock deleted file mode 100644 index 6917c23..0000000 --- a/ai/worker.lock +++ /dev/null @@ -1 +0,0 @@ -32960 \ No newline at end of file diff --git a/backend/app/config.py b/backend/app/config.py index e27ff2b..e4f309f 100644 --- a/backend/app/config.py +++ b/backend/app/config.py @@ -9,7 +9,7 @@ from pathlib import Path DEFAULT_HOST = "127.0.0.1" DEFAULT_PORT = 8000 DEFAULT_STORAGE_FILENAME = "hll_vietnam_dev.sqlite3" -DEFAULT_REFRESH_INTERVAL_SECONDS = 60 +DEFAULT_REFRESH_INTERVAL_SECONDS = 120 DEFAULT_ALLOWED_ORIGINS = ( "null", "http://127.0.0.1:5500", diff --git a/backend/data/.gitkeep b/backend/data/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/backend/data/.gitkeep @@ -0,0 +1 @@ + diff --git a/backend/data/hll_vietnam_dev.sqlite3 b/backend/data/hll_vietnam_dev.sqlite3 deleted file mode 100644 index e9684e61ca938d5395bb3bd6e11da93de529d309..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 40960 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