Instala @rokmohar/medusa-plugin-meilisearch@^1.4.1 (linea v1, la unica
compatible con nuestro Medusa 2.18.0 exacto -- confirmado contra
peerDependencies reales de npm: @medusajs/* ^2.15.2, satisfecho por
2.18.0). Conectado via un array `plugins:` nuevo en medusa-config.ts
(primer uso en este repo, no `modules:`), env vars leidos con `?? ""`
en vez de required() -- si Meilisearch esta caido o mal configurado,
el plugin se degrada solo en vez de tumbar el arranque de Medusa
entero.
No se escribe un subscriber propio: se verifico contra el codigo
fuente real del paquete (descargado el tarball exacto de npm,
inspeccionado en /app/node_modules dentro de una imagen Docker de
verdad) que trae sus propios subscribers de product/category/
collection/variant/etc, descubiertos por Medusa en runtime desde
dentro del propio paquete -- confirmado que sobreviven a
`npm prune --omit=dev` y llegan intactos a la imagen final. Tambien
trae un job de indexado inicial de una sola corrida al boot
(numberOfExecutions: 1, no un cron recurrente -- no viola la
restriccion del ADR de "nunca cron").
Nueva ruta Store API propia (src/api/store/search/route.ts): las
rutas /store/meilisearch/* que trae el plugin no devuelven
facetDistribution (verificado leyendo su codigo fuente), asi que esta
ruta pide facets explicitamente via additionalOptions.facets, y
despues re-hidrata los productos via query.graph (mismos campos que
ya usa el storefront) en vez de confiar en precios/inventario
indexados -- mismo patron "safe path" que ya usa la ruta oficial del
plugin para /store/meilisearch/products.
Transformer custom en medusa-config.ts que espeja mapProduct() del
storefront (category/collection/brand/ageRange desde metadata,
disponibilidad desde la primera variante) para que el documento
indexado sea exactamente lo que el storefront ya muestra.
Validado en vivo: build completo de Docker (target builder) corre
limpio -- npm ci, medusa build (typecheck + compile backend/frontend),
npm prune -- cero errores. package-lock.json regenerado con un
contenedor node:22.18.0-bookworm-slim real (mismo base image que el
Dockerfile), no a mano.
Dockerfile: dummy MEILISEARCH_HOST/MEILISEARCH_API_KEY en el stage de
build (insurance barata, no son required() asi que no eran
estrictamente necesarios para que el build pasara, y de hecho paso
sin ellos en la prueba -- se dejan de todas formas por consistencia
con el resto de dummies de esa capa).
Motor de busqueda self-hosted, sin que Medusa lo conozca todavia
(eso es Fase 2). Mismo patron que redis/postgres/minio en este mismo
namespace: StatefulSet + PVC via volumeClaimTemplates en local-path,
nunca Deployment ni emptyDir -- el indice de Meilisearch necesita
sobrevivir a un reinicio del pod para no reindexar todo desde cero.
Imagen getmeili/meilisearch:v1.53.1 (ultimo release estable no-RC,
verificado contra la API de GitHub, no memoria de entrenamiento).
Recursos exactos del ADR (request 100m/256Mi, limit 500m/768Mi).
Sin securityContext explicito -- verificado en vivo que la imagen no
trae un usuario no-root (Alpine minimo, /etc/passwd sin usuario
dedicado), misma convencion que redis.yaml/minio.yaml en este repo,
que tampoco fuerzan runAsNonRoot.
MEILISEARCH_HOST (no secreto) va al ConfigMap commerce-config.
MEILI_MASTER_KEY/MEILISEARCH_API_KEY (mismo valor, dos nombres de env
var -- uno para el servidor, otro para el futuro plugin de Medusa en
Fase 2) documentados en secrets.template.yaml; el valor real ya se
aplico al Secret commerce-secrets en el cluster antes de este merge
(patch puntual, no via create-commerce-secrets.sh completo -- ese
script regenera TODAS las credenciales en cada corrida y hubiera
rotado postgres/redis/minio ya en uso).
Aprobada tras el diagnóstico de memoria del host (swap saturado
resuelto, ~500-700MiB liberados al desactivar monitoring). Agrega
nota de implementación con 3 desviaciones reales encontradas al
verificar el código fuente del plugin en el tag v1.4.1 antes de
escribir código: no hace falta subscriber propio (el plugin trae los
suyos), las rutas del plugin no devuelven facetDistribution (se
agrega una ruta Store API propia), y se conecta vía plugins: no
modules:. Ninguna cambia la decisión, solo el cómo.
Sin uso actual, y el host está evaluando capacidad de memoria para la
Etapa 2 del ADR 0006 (Meilisearch) con swap bajo presión. Se quita del
app-of-apps para liberar los recursos del namespace `monitoring`
(Grafana, Prometheus, Alertmanager, kube-state-metrics,
prometheus-operator -- estos dos últimos venían en CrashLoopBackOff
desde hace 37 días, ~8000 reinicios cada uno, conexión rechazada
contra el apiserver in-cluster -- y los 3 node-exporter).
Reversible: reagregar ambos archivos re-despliega el stack completo
vía Helm/kustomize sin pasos manuales. Sin pérdida de datos -- el
namespace monitoring no tenía ningún PVC, confirmado antes de borrar
(kubectl -n monitoring get pvc -> vacío).
Se agregó el finalizer resources-finalizer.argocd.argoproj.io a ambas
Applications (monitoring-app, monitoring-governance) antes de este
commit para que Argo CD borre en cascada los recursos desplegados al
podarlas, no solo el objeto Application -- sin eso quedarían pods
huérfanos corriendo sin liberar memoria.
commerce.cruzcloud.net (medusa-svc) has no route at "/" — Medusa only
serves /health, /app (admin), /store, etc. lab-agent's generic public
domain check flagged the resulting 404 as an anomaly every cycle even
though the service is healthy.
Adds a Traefik Middleware (redirectRegex) scoped to the commerce host
that 301s "/" to "/app", so the DNS/routing layer owns the entry point
instead of every client (including monitoring) having to know to
append /app manually. Regex includes the host explicitly because the
same Ingress also routes media.cruzcloud.net and shares
router.middlewares at the Ingress-annotation level.
Documenta el cambio a Telegram (silencioso para info, hilos al
recuperarse, log adjunto), la pausa nocturna 06:00-23:00 con su
tensión sin resolver con la ventana de medusa-deploy, la activación
del timer de systemd (60 min, bajado de 15 para reducir costo) con el
gotcha de Environment=HOME= para systemd --user, y el costo mensual
estimado actualizado.
17 corridas/día en vez de 68. Nota importante: el costo por corrida
sube al perder la ventaja del cache tibio de Claude Code (~1h TTL,
corridas espaciadas 60 min lo pierden casi siempre) -- el ahorro real
es ~1.5-2x, no 4x. También documenta el trade-off de latencia de
detección (~70 min en vez de ~25 min hasta detectar un problema).
Timer activo desde 2026-08-26. Documenta el hallazgo en vivo: el
manager de systemd --user de devops arranca con HOME=/DATA (el de
/etc/passwd), no con el override de /etc/profile.d/zz-devops-home.sh
que solo aplica a shells interactivas -- sin Environment=HOME=... en
la unidad, claude -p habría fallado la autenticación en cada corrida
del timer, silenciosamente. Se detectó y corrigió antes de activar,
corriendo el servicio manualmente vía systemctl --user start con el
entorno real como último paso de validación.
Actualiza la sección de Notificaciones: formato con íconos por tipo de
evento, log completo adjunto como documento, nivel "info" silencioso
(disable_notification), y respuestas en hilo cuando un recurso
accionado se recupera solo -- con la limitación conocida de que un
desbloqueo manual (borrando la entrada de state.json) pierde el
message_id y no queda threadeado. Validado en vivo con el canario.
Actualiza docs/arquitectura/agente-monitoreo.md: canal de notificación
cambiado de ntfy a Telegram Bot API (con la evidencia de la prueba de
entrega), horario activo 06:00-23:00 con su justificación de costo, la
tensión sin resolver con la ventana de medusa-deploy (00:00-06:00, no
se solapa con el horario activo del agente), y la estimación de costo
mensual (~US$60-65, basada en las corridas reales medidas).
Documentación de gobernanza y arquitectura del agente lab-agent:
lista blanca aprobada, diseño de seguridad (--allowedTools "" en vez
de un Bash tool con patrón, por la vulnerabilidad de coincidencia por
prefijo encontrada en vivo), autenticación por login de suscripción, y
evidencia completa de la prueba end-to-end del 2026-08-26.
Agrega docs/arquitectura/agente-monitoreo.md como referencia técnica y
documento de gobernanza del wrapper headless de diagnóstico/corrección
(scripts/lab-agent). Cubre la lista blanca de acciones automáticas
aprobada, por qué Claude corre con --allowedTools "" en vez de un Bash
tool con prefijo (coincidencia por prefijo permite inyección de
comandos, confirmado en vivo), el rediseño de autenticación a login de
suscripción en vez de API key, y la evidencia completa de la prueba
end-to-end del 2026-08-26 (DRY_RUN, ejecución real, rate limit/bloqueo,
2 bugs encontrados y corregidos).
Etapa 1 (auditoria/propuesta, sin codigo) de la Etapa 3 de Fase 5:
motor de busqueda y filtros facetados reales, reemplazando el
filtrado/conteo 100% client-side que dejo la sub-fase 3 de Etapa 2.
Verificado contra documentacion oficial vigente (no memoria de
entrenamiento):
- Medusa no tiene modulo de busqueda propio integrado con
Meilisearch; el Search Module nativo llego en Medusa 2.19, y el
plugin comunitario @rokmohar/medusa-plugin-meilisearch se conecta a
el solo desde su version ^2.0.0 (requiere Medusa >=2.19). Nuestro
backend corre Medusa 2.18.0 -- la version compatible es la linea
^1.4.1 del plugin (Medusa >=2.15 <2.19), documentada como deuda
tecnica explicita si se sube Medusa mas adelante.
- Impacto de recursos evaluado contra el estado real del host (swap
al 100%, mismo tipo de contencion que el incidente de Gitea):
Meilisearch recomendado sobre Typesense por menor huella de RAM y
por ser el unico con integracion Medusa mantenida para nuestra
version -- comparacion mantenida breve porque la diferencia es
clara, sin profundizar mas de lo necesario.
- Diseno de indexacion (campos buscables/filtrables/ordenables),
sincronizacion (mismo patron de subscriber por eventos que
revalidate-storefront.ts, sumando product-category.* al set de
eventos) y UI de facetas/autocompletado (reutiliza catalog-client.tsx
y CatalogProvider.searchProducts ya existentes, sin componentes
nuevos).
Cross-referencia agregada en ADR 0004 (que ya habia identificado
Meilisearch como paso natural) y entrada nueva en mkdocs.yml.
Etapa 2 (implementacion) NO arranca hasta aprobacion explicita de esta
propuesta.
Estado seguia diciendo "propuesta -- pendiente de aprobacion antes de
Etapa 2" aunque las 3 sub-fases (datos/categorias, navegacion,
componentes visuales -- PRs #29-#42) ya estan implementadas y en
produccion desde el 2026-08-25. Actualiza el header de estado y
reemplaza la seccion 6 (antes "Proximos pasos" pendiente de
aprobacion) por el resumen real de lo ejecutado, dejando explicito que
sigue pendiente borrar el usuario admin temporal de la auditoria y que
no hay Etapa 3 definida todavia.
tsconfig tiene noUncheckedIndexedAccess -- promoRoots[promoIndex %
promoRoots.length] tipa como Category | undefined aunque en runtime
siempre es valido (promoRoots.length > 0 ya se verifico antes de este
punto). Extraido a una constante con guard explicito para que TS
angoste el tipo. Sin cambio de comportamiento.
Detectado por el build real en main tras el merge de #41 -- no se
puede correr tsc localmente en esta maquina (ver notas de sesiones
anteriores), asi que esto solo lo valida el CI post-merge.
ADR 0005 seccion 3 (patron Walmart), ultimo item de la sub-fase de
componentes visuales: "grid de catalogo con tiles promocionales
intercalados, no solo tarjetas de producto homogeneas".
`category-tiles.tsx` ya era ese mismo primitivo visual (usado en el
home) -- se extrajo el tile individual a un componente exportado
`PromoTile` (mismo look, sin cambio visual en el home) para
reutilizarlo en `catalog-client.tsx`: un tile cada
PROMO_TILE_INTERVAL=8 productos, ciclando por las categorias raiz
(excluye la raiz que el usuario ya esta viendo via el breadcrumb de
#40). Si no hay jerarquia de categorias disponible, la grilla queda
igual que antes (solo productos) -- degradacion sin romper nada.
Depende de #40 (breadcrumb + categoryNodes en CatalogClient) -- mismo
archivo, se apila sobre esa rama en vez de main.
ADR 0005 seccion 3 (patron Amazon), primer item de "Filtros facetados
en sidebar con breadcrumb de categoria":
- Breadcrumb (Inicio > raiz > hija) armado caminando parentId sobre la
jerarquia real de categorias (misma que ya consume el mega-menu de
navbar.tsx), no un dato nuevo -- CatalogClient ahora recibe el
arreglo `categories: Category[]` completo ademas del
`categoryGroups` ya existente
- Conteo por valor en cada filtro de la sidebar (Categoria/Marca/Edad),
ej. "Marca (12)": se calcula client-side sobre los productos que ya
pasan el resto de filtros activos, cada dimension excluyendose a si
misma (patron faceted-count estandar). Sin Meilisearch por ahora,
como preveia el ADR ("server-side simple por ahora")
Filtrado existente refactorizado a funciones matchesX() puras y
reutilizadas tanto por `filtered` como por los conteos, sin cambiar el
comportamiento de filtrado ya validado.
Expone ProductVariant.inventoryQuantity (ya calculado desde
variant.inventory_quantity en Medusa, hoy colapsado al booleano
available) y lo usa para mostrar "Quedan N" cuando el stock real es
bajo (<=5), tanto en la tarjeta de producto como en la ficha. null
indica inventario no gestionado (backorder / manage_inventory=false),
donde nunca se muestra un numero. ADR 0005 seccion 3 (patron eBay).
Catalogo mock actualizado (data/products.json) con
inventoryQuantity=null en todas las variantes para seguir tipando
contra Product[] via `satisfies`.
Reutiliza Product.variants[].{name,value,available}, ya expuesto por el
provider de Medusa (variant.options[0]), para swatches clicables en la
tarjeta del catalogo/home -- no solo en la ficha de producto. Solo se
muestra cuando el producto tiene mas de una variante; la variante
seleccionada se usa al agregar al carrito. ADR 0005 seccion 3 (patron
eBay), cero cambio de modelo de datos.
Reutiliza Product.compareAtPrice (ya calculado en el provider de Medusa
via original_amount > calculated_amount) para mostrar precio tachado +
badge de descuento en la grilla/catalogo, no solo en la ficha de
producto. ADR 0005 seccion 3, patron Walmart -- cero cambio de modelo
de datos.
Reemplaza la fila horizontal de pildoras por categoria (ADR 0005 seccion
3, patron Walmart) por un trigger unico "Departamentos" que abre un
panel multi-columna con las 6 categorias raiz y sus hijos, activado por
hover (mouse) o tap (touch), con cierre por click-fuera y Escape.
Bug preexistente (no introducido en esta sesion, solo expuesto): "/" se
prerenderizaba en build time dentro del Dockerfile, donde
HEADLESS_PROVIDER/MEDUSA_* no existen todavia (solo se inyectan en runtime
via el Deployment de k8s) -- el provider caia a "mock" y ese HTML quedaba
cacheado 1 año (confirmado en vivo: x-nextjs-prerender:1,
Cache-Control: s-maxage=31536000, x-nextjs-cache:HIT). El carrusel de
"Novedades" del home ya mostraba productos mock desde antes; recien se
noto con el nav data-driven de la sub-fase 2 porque las categorias mock
("Figuras"/"Peluches"/"Mochilas") son obviamente distintas a las reales.
/catalog y /product/[slug] no sufren esto porque ya son dinamicos
(searchParams / params fuerzan SSR).
export const dynamic = "force-dynamic" en app/page.tsx y app/layout.tsx
(el layout comparte el fetch del Navbar con TODAS las rutas -- forzarlo
ahi tambien protege contra que una pagina futura reintroduzca el mismo
bug). Decision del usuario: priorizar datos reales sobre el cacheo
estatico de 1 año.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_013dunTcReWMKhWgCPkvAVHD
next build fallaba en tsc: defaultTile no tenia la propiedad opcional
image, asi que la union de tipos entre tileContent[handle] y defaultTile
perdia esa propiedad y content.image no compilaba. Se extrae el tipo
TileContent y se anota defaultTile con el, igual que tileContent.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_013dunTcReWMKhWgCPkvAVHD
devops
gitea-actions