Publish

El ciclo de vida de publish

Publicar un workspace es un ritmo de cuatro pasos — leer el estado local, ver qué difiere, validar, push. Corré todos estos desde el root del workspace (o cualquier subdirectorio adentro):

looky status     # confirmar root, instancia, billing, workspace, sync state
looky diff       # mostrar diferencias de archivos local-vs-server
looky validate   # correr el gate de validación
looky push       # publicar content (solo después de que validate esté limpio)

push corre el mismo gate de validación que validate y se rehúsa a publicar si algo falla — validate es la forma de correr ese gate sin publicar.

Dos scopes de push — content vs settings

looky push apunta a una de dos superficies distintas, nunca a las dos a la vez:

• Default (content push) — publica content/** + workspace.yml. Gateado fuerte por la validación. Falla si tu configuración de runtime todavía no se deployó.
• --settings (config push) — publica runtime/** + secrets/**. Valida las declaraciones de source y después escribe. Usalo en setup inicial, después de rotar credentials, o cada vez que cambies declaraciones de source.

Orden típico de primera vez: looky push --settings primero para deployar sources + secrets, después looky push para content.

Qué chequea la validación

Cuando corrés looky validate o looky push:

• Pasada local. El YAML parsea, los archivos referenciados existen, los IDs son únicos, query usa el separador ::, los dashboards referencian visualizations reales, los exports referencian dashboards reales, las expresiones cron son válidas, el bloque chart de cada visualization pasa su schema tipado.
• Pasada server. Los aliases de source son alcanzables, cada model Malloy compila, cada visualization publicada hace dry-run limpio contra las data sources configuradas.

Si algún check falla, el comando sale no-cero e imprime el código de error, el path del archivo, y un mensaje legible. Los warnings no bloquean — aparecen en el output y dejan que el push proceda.

Flags de validación

• --strict — suma validación live-source por visualization. En Postgres, corre EXPLAIN contra la base live (un round-trip por viz, con timeout de statement de 10 segundos). En BigQuery, corre estimateQueryCost (gratis, sin bytes escaneados). Atrapa errores de dialecto y permisos faltantes que la pasada rápida default no puede. Usalo antes de un release; salteatelo para iteración rápida.

Para validar sin publicar, usá looky validate. En push, el cliente es la fuente de verdad del scope de content — archivos presentes en el server pero ausentes localmente se borran como parte del push.

Familias de error code

Los errores y warnings de validación se taggean con un prefix de código estable. El prefix te dice qué gate se disparó y a qué familia de archivos concierne.

• WS*** — issues de workspace.yml (campos faltantes, shape inválido de identifier, billing account desconocido).
• RT*** — declaraciones de runtime / source (tipo de source faltante o no soportado, credentials_file faltante, dsn faltante para postgres, archivo de credenciales no encontrado en secrets/). Mayoritariamente warnings.
• MD*** — issues de archivo de model (referencia a alias de source faltante, archivo fuera de content/, archivo no legible).
• VZ*** — estructura YAML de visualization (id/title/type/query faltantes, referencia de query malformada, id duplicado).
• VZ020, VZ021 — violaciones de schema tipado de visualization: una propiedad chart.* que no está en el schema, un tipo equivocado, un valor fuera de rango.
• DB*** — issues de YAML de dashboard (campos faltantes, layout_mode no en fluid_grid / document, referencias a visualizations desconocidas).
• EX*** — issues de YAML de export (formato cron, referencia a dashboard desconocido).
• MR*** — errores de runtime reportados por el server. MR000 falla de carga, MR001 error de compile / parse de Malloy, MR002 field no definido, MR003 alias de source desconocido, MR004 introspección de schema fallida, MR005 query engine inalcanzable, MR006 query engine timeouteó, MR008 archivo de model faltante, MR009 catch-all de precheck, MR010 source inalcanzable desde la probe.

Qué sube el push

Un content push exitoso publica el set de archivos validado y reporta counts de archivos created / updated / unchanged / deleted. El disaster recovery es tu responsabilidad — mantené el workspace en git, o apoyate en el snapshot local .bk/<timestamp>/ que looky pull escribe cuando sobrescribe archivos locales.

Un settings push exitoso publica runtime/sources.runtime.yml y los archivos de secrets/ referenciados por él. La validación corre primero; si falla, el push imprime los issues y no se escribe nada.

Verificación post-publish

1. Corré looky list visualizations y looky list dashboards — confirmá qué hay publicado realmente en el server.
2. Abrí https://my.looky.studio y confirmá que los dashboards renderizan.
3. Abrí al menos una página de detalle de visualization y confirmá que aparece data. La validación no chequea que los nombres de campo en mapping matcheen el resultado de la query; eso recién aparece cuando el chart efectivamente renderiza.
4. Si un dashboard renderiza en blanco o un chart muestra "no rows", chequeá la query de model subyacente en la página de detalle de la visualization — esa es la traza más directa.

Playbook de recovery de fallas

• La validación falló localmente (WS / RT / MD / VZ / DB / EX). Leé el código de error y el path del archivo; arreglá el YAML; re-corré looky validate.
• La validación falló en la pasada server (MR* o VZ020). El error menciona el model o visualization que lo disparó. Abrí ese archivo, arreglá el Malloy o spec de chart, re-corré looky validate. Si el error es MR010 (source inalcanzable), confirmá que looky push --settings haya corrido exitosamente recientemente con las credentials actuales. Cuando el server reporta cualquier error, nada en el workspace se modifica.
• El push pasó pero el dashboard está mal en el sitio live. Los archivos se publicaron bien pero un chart está fallando al renderizar. Chequeá nombres de campo en mapping, format keys, y el output real de la query en el viz detail.
• Necesitás deshacer un push. Restaurá el contenido previo desde git o desde el directorio local .bk/<timestamp>/ que looky pull escribió, y volvé a pushear con looky push.