@griddo/cx 11.9.12-rc.0 → 11.9.12

package/README.md

@@ -1,19 +1,246 @@
-# Griddo Generator
+# Griddo CX
 
-Este documento describe el flujo del render en Griddo Generator y otros aspectos técnicos relevantes.
+Griddo CX es un package dentro del monorepo de Griddo (`packages/griddo-cx`) que se encarga de ofrecer herramientas para orquestar el render de una instancia utilizando la biblioteca de componentes, un framework SSG y los datos obtenidos de la API privada de Griddo.
 
----
+# Arquitectura
 
-- [Render flow](./docs/RENDER-FLOW.md)
-- [Incremental render flow](./docs/INCREMENTAL-RENDER.md)
-- [Directorios](./docs/DIRECTORIES.md)
-- [CLI](./docs//CLI.md)
+CX está escrito como una biblioteca en TypeScript. \**Los consumidores de la misma son el *Adapter, el framework SSG y una serie de scripts en TypeScript que viven en el propio `package/griddo-cx` y que son utilizados por infra, normalmente invocados mediante un `npm run ...`
 
+\*Para los casos del Adapter y los “scripts para infra”, estos utilizarán directamente el código Typescript de la biblioteca de CX. Para el caso del SSG, este utilizará el código bundlelizado disponible en `@griddo/cx` y `griddo/cx/react`
 
-## TODO:
+Como ejemplo aquí vemos un snippet dentro de Gatsby (actual framework SSG) importando un componente `<GriddoIntegrations>` que forma parte de la biblioteca de CX, en concreto del export de react.
 
-- Implementar `--root` en el CLI, solo en el `prepare-domains-render` y este ya lo deja escrito en `db.json`
-- Usar el CLI en infra.
-- Optimizar el caso en que un dominio solo tenga páginas para despublicar y/o eliminar. En esta situación, no sería necesario ejecutar Gatsby; bastaría con una sincronización para eliminar los archivos html y page-data correspondientes y regenerar los sitemaps.
-- Rollback. Ver qué hacemos con el dist-backup... copy y después rsync.
-- Usar db.json en lugar de archivo domains si es posible... (actualmente se lee domains.json)
+```tsx
+// src/components/template.tsx
+import { GriddoIntegrations } from "@griddo/cx/react";
+```
+
+## Exports
+
+CX tiene dos exports separados: **main y react**.
+
+- **main** se exporta en `@griddo/cx` . Es código que se ejecuta en un entorno nodejs.
+- **react** se exporta en `@griddo-cx/react` . Es código React :)
+
+**Ejemplo de import**
+
+```tsx
+// React import
+import { GriddoIntegrations } from "@griddo/cx/react";
+// Core import
+import {
+	IS_COMPONENT_LIBRARY,
+	PROJECT_ALIASES,
+	resolveComponentsPath,
+} from "@griddo/cx";
+```
+
+## Bundle
+
+El bundle del código TypeScript se genera con [esbuild](https://esbuild.github.io/). Compilando el código a CommonJS junto con las definiciones de tipos.
+
+Se puede ejecutar el bundle de todo CX con `yarn run build` desde `packages/griddo-cx` . Esto creará los distintos exports: _node_, _react_ y también los scripts para _infra_: reset-render, build-complete y upload-search-content junto con los archivos de definición de tipos.
+
+Este comando, `yarn run build` se ejecuta en el despliegue del monorepo, npm prepare, etc. No es necesario que manualmente hagamos un build para los despliegues.
+
+# Features
+
+## Archivo de configuración
+
+CX tiene un archivo de configuración en el raíz del package `griddo-cx/cx.config.js` donde se establecen ciertos valores globales para todo el package.
+
+Los siguientes puntos están incluidos en el archivo de configuración y deben ser leídos de este, evitando hardcodear o volver a calcularlos en el resto del código.
+
+```jsx
+const config = {
+	proDomain: "pro-", // Prefijo para los dominios "pro"
+	griddoVersion, // Versión de griddo obtenida del package.json
+	buildReportFileName: "build-report.json", // Archivo de reporte de render
+	// función que resuelve la ruta absoluta a los placeholders
+	paths: (domain) => ({
+		__cache: path.join(CX_CACHE_DIR, domain || ""),
+		__components: COMPONENTS_DIR,
+		__cx: CX_ROOT_DIR,
+		__exports: path.join(EXPORTS_DIR, domain || ""),
+		__root: REPO_ROOT_DIR,
+		__ssg: SSG_DIR,
+	}),
+};
+```
+
+El contenido del archivo de configuración se leerá con la función `getConfig()` donde sea que necesitemos acceder a la misma.
+
+**Ejemplo**
+
+```tsx
+const config = getConfig()
+const { proDomain, ... } = config
+```
+
+### Dominio \*pro-\*\*
+
+En los renders de Griddo se diferencia cuando el render es de un dominio de producción, esto es que el dominio interno empieza por `pro-` , por ejemplo `pro-griddo`
+
+Este `pro-` se especifica directamente y una sola vez en el archivo de configuración.
+
+### Versión de Griddo
+
+Si es necesario obtener la versión de CX la podemos tomar directamente del archivo de configuración
+
+### Sistema de paths interno
+
+Mediante el archivo de configuración se establecen unas rutas absolutas globales a todo CX e instancia (ya sea instancia interna del monorepo o la de un cliente) que nos ayudará a orquestar los artefactos durante los LifeCycles de un render. Un uso parecido a los `__dirname` o `__filename` de javascript CommonJS.
+
+**Rutas con el dominio actual concatenado**
+
+Ya que la mayoría de las veces el uso de estas rutas son durante el render de un dominio, la ruta incluirá el dominio para así hacer operaciones más fácilmente sin tener que estar adjuntándolo (concat) constantemente. Esto es así para los placeholders `__exports` y `__cache` . Para ello a `paths()` hay que pasarle el dominio como único argumento cuando obtengamos las rutas con `config.paths()`
+
+**Ejemplo**
+
+```tsx
+const { __exports, __cache } = getConfig().paths("mi-dominio");
+console.log(__exports); // ...export/sites/**mi-dominio**
+console.log(__cache); // ...griddo-cx/.cx-cache/**mi-dominio**
+```
+
+Esta son las rutas existentes.
+
+- `__cx` La ruta absoluta del package de CX
+- `__ssg` La ruta absoluta del SGG configurado
+- `__exports` La ruta donde se aloja el render final
+- `__cache` La ruta del caché de CX, donde se guardan artefactos entre renders
+- `__components` La ruta de la instancia. En el monorepo la de `griddo-components`
+- `__root` El directorio raíz siempre, en el monorepo y en la instancia. (uso residual)
+
+**Ejemplo de uso real**
+
+```tsx
+import { getConfig } from "./utils/config";
+
+// Sin dominio
+const config = await getConfig();
+const { __cx, __ssg } = config.paths();
+const storeDir = path.join(__cx, "store");
+const templateFile = path.join(__ssg, "src/components/template.tsx");
+
+// Con dominio
+const { __cache } = config.paths("pre-griddo");
+console.log(__exports); // /griddo/packages/griddo-cx/.cx-cache/**pre-griddo**
+```
+
+## LifeCycles
+
+Los LifeCycles se utilizan dentro del contexto de un _Adapter_. Se usa a través de la función `doLifeCycle` que ejecuta un batch de funciones (`actions`) de forma secuencial. Informando por consola del inicio, fin y tiempo invertido en ejecutar todas las funciones del `actions`, manejando cualquier error en las mismas. En caso de error, es posible indicar un número de _attempts_ que hará que se ejecute de nuevo el clico de vida las veces indicadas.
+
+En CX existen estos LifeCycles: `Prepare`, `Restore`, `Data`, `SSG`, `Relocation`, `Meta`, `Archive`, `Clean`, `HealthCheck` y uno de `__DEBUG__` internamente son iguales (usan `doLifeCycle`) y se utilizan estos distintos nombres para identificarlos dentro de un render, poner distintos _attempts_, etc..
+
+**Ejemplo:**
+
+```tsx
+await doLifeCycle({
+	name: "SSG",
+	attempts: 2, // intentará hacer **todos** las actions dos veces si hay un error en alguno de ellos
+	actions: [func1, func2, func3],
+});
+```
+
+# Scripts para infra.
+
+Como hemos visto uno de los consumidores de CX son scripts “individuales” que están alojados en `griddo-cx/src/scripts` Estos scripts son siempre llamados por infra, o por el desarrollador cuando se hacen render en local.
+
+## `start-render`
+
+CX es una biblioteca por lo tanto no tiene nada ejecutable como tal, no hay un entry point desde el punto de vista del _package_. En el package.json existe un binario `griddo-cx` que usa infra/API para ejecutar un render, este binario apunta a `griddo-cx/start-rener.js` con el que se desencadena el proceso de publicación.
+
+## `reset-render`
+
+Lo ejecuta infra mediante `yarn run reset-render` . Este resetea la API en caso de que un render salga mal. De esa manera la API al ser preguntada volverá a comunicar que hay un render pendiente y comenzará con ello de nuevo.
+
+Si no se llamase correctamente al script, la API se quedaría esperando a que finalice el render “eternamente”. Hay un time-out de X horas.
+
+## `build-complete`
+
+Lo ejecuta infra mediante `yarn run build-complete` cuando un render acaba de manera exitosa y el contenido ha sido subido al servidor, es decir, cuando se ha completado **una publicación**. Este script envía a la API información del render y le comunica que este ha terminado y que está disponible para un rrnuevo render.
+
+## `upload-search-content`
+
+Lo ejecuta infra mediante `yarn run upload-search-content` cuando un render ha acabado o con cierta frecuencia. Sube contenido de los estáticos del render a un endpoint para el uso en buscadores.
+
+# Adapter
+
+Un Adapter es una función que se ejecuta en el script `start-render.js` que es el que se triggea cuando API avisa de un nuevo render. Los Adapters están en el directorio `griddo-cx/exporter/adapters`
+
+El Adapter es el responsable de manejar el proceso de render mediante las utilidades de la biblioteca. En el proceso puede hacer lo que estime oportuno salvando ciertas obligaciones para que un render sea Griddo-compliant.
+
+<aside>
+💡 Los Adapters utilizarán el código TypeScript de CX, no el bundlelizado. Ya que el propio adapter también se bundleliza.
+
+</aside>
+
+### **Obligaciones de un Adapter**
+
+**Exports**
+
+**Dist**
+
+Dejar una carpeta con los archivos estáticos finales en el path `__exports` , que es una carpeta `exports/sites/<dominio>/dist` donde `dominio` es cada dominio de la instancia de Griddo. Una vez terminado el render, _infra_ tomará esa carpeta y la subirá. Infra la sube mediante sincronización por lo que siempre tiene que estar actualizada y con la totalidad de los datos. Si en la carpeta destino hay un archivo que no existe en la carpeta fuente `exports/sites/<dominio>/dist` se borrará.
+
+**Assets**
+
+Igualmente dejar una carpeta con los “assets” de javascript. Esto es verdad en el mundo Gatsby no sabremos qué pasará con otros frameworks.
+
+**Caches**
+
+El adapter deberá manejar manualmente la caché de Griddo utilizando las funciones `moveDirsSync`, `copyDirsSync` y `removeDirsSync`.
+
+La caché de Griddo son dos directorios que se crean en `griddo-cx` por cada render y dominio: `store` y `apiCache` . Para facilitar el trabajo CX cuenta con placeholders para las rutas, en este caso `__cache` que haría referencia `griddo-cx/.cx-cache/<domain>`
+
+```tsx
+griddo-cx
+|-.cx-cache
+  |- store
+  |- apiCache
+```
+
+¿Cómo se maneja la caché? ¿Qué hago con ella?
+
+Los datos de la caché se generan de forma automática en `griddo-cx`El manejo se basa en _restaurar (Restore)_, _archivar_ (Arhive) o _invalidar (Clean)_ los directorios de la caché, tanto `store` como `apiCache`
+
+**Restaurando la caché**
+
+Cuando se inicia un render debemos mover tanto `store` como `apiCache` que estarán dentro de `griddo-cx/.rendrr-cache/<dominio>` al raíz de CX `griddo-cx` para que el proceso de render haga uso de las mismas.
+
+**Archivando la caché**
+
+Cuando el render de un dominio termina correctamente, se deben mover las carpetas `store` y `apiCache` a la carpeta de caches `griddo-cx/.cx-cache/<domain>` para poder restaurarlas en un próximo render.
+
+**Invalidando la caché**
+
+Si un render ha dado error pueden quedarse en el raíz de CX las carpetas `store` y `apiCache`. **Estas deben ser borradas** antes de la nueva fase de restauración. De hecho probablemente no exista nada que restaurar porque el render dio error. En ese caso lo que ocurre es que efectivamente no hay nada que restaurar y habrá que descargarse de nuevo todos los datos.
+
+A su vez, en cada despliegue que exista en la instancia también se borrarán ya que de alguna manera se alojan en lo que sería el `node_modules` de la instancia. Y se borrará CX enteramente.
+
+<aside>
+💡 Coming soon: Gestión automática de la caché de Griddo (no de los frameworks SSGS)
+
+</aside>
+
+# Logs
+
+…
+
+# Errores
+
+…
+
+# Testing
+
+…
+
+# FAQ’s
+
+### ¿Griddo procesa imágenes en tiempo de render?
+
+No, los proyectos actuales de Griddo se apoyan en imágenes alojadas en remoto, en concreto en un servicio externo “DAM” propiedad de Secuoyas. Este servicio ofrece las transformaciones necesarias. Existen un componente de React en Griddo `<GriddoImage>` que las instancias pueden utilizar y que se integra con el “DAM”.
+
+Algunas de las primeras instancias utilizan la misma estrategia con cloudinary, usando un componente de React proporcionado también por Griddo: `<CloudinaryImage>`

package/build/adapters/gatsby/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Render every instance domain with the Gatsby adapter.
+ */
+export declare function renderDomainsWithGatsbyAdapter(domain: string): Promise<void>;

package/build/adapters/gatsby/utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Return the assetPrefix with the domain concatenated `assetPrefix/domain` only
+ * if the domain is "pro-" **and** there is a env `GRIDDO_ASSET_PREFIX` with any
+ * value different from `null`, `undefined` or `empty string`
+ *
+ * else...
+ * - If assetPrefix or domain is falsy, returns ""
+ * - If the domain is not "pro-", returns ""
+ */
+declare function getGatsbyAssetPrefixWithDomain(domain: string): string;
+/**
+ * Spawn a new node process `yarn gatsby-build`
+ * @note This proccess (`yarn gatsby-build`) can not access to the custom Griddo
+ * `process.env` so it needs variables passed to it via the `env` prop.
+ */
+declare function runGatsbyBuildCommand(assetPrefixWithDomain: string): void;
+/**
+ * Update the Griddo's `/dist` dir with the contents from `public` dir only
+ * with files of type: js, json and css.
+ */
+declare function createDistFromGatsbyPublic(domain: string, needsAssetPrefix: boolean): Promise<void>;
+export { createDistFromGatsbyPublic, getGatsbyAssetPrefixWithDomain, runGatsbyBuildCommand, };

package/build/artifacts/index.d.ts

@@ -0,0 +1,6 @@
+import type { Artifacts } from "../types/global";
+/**
+ * Returns the artifacts of CX.
+ */
+declare function getCxArtifacts(domain: string): Artifacts;
+export default getCxArtifacts;

package/build/commands/end-render.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};

package/build/commands/reset-render.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};

package/build/commands/start-render.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};

package/build/commands/upload-search-content.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};

package/build/constants/envs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Here are all the environment variables that the CX code uses.
+ */
+declare const GRIDDO_API_URL: string | undefined;
+declare const GRIDDO_PUBLIC_API_URL: string | undefined;
+declare const GRIDDO_BOT_USER: string | undefined;
+declare const GRIDDO_BOT_PASSWORD: string | undefined;
+declare const GRIDDO_API_CONCURRENCY_COUNT: number;
+declare const GRIDDO_RENDER_ALL_SITES: boolean;
+declare const GRIDDO_RENDER_SITE: number;
+declare const GRIDDO_RENDER_PAGES: number[];
+declare const GRIDDO_SKIP_BUILD_CHECKS: boolean;
+declare const GRIDDO_DEBUG_LOGS: boolean;
+declare const GRIDDO_BUILD_LOGS: boolean;
+declare const GRIDDO_RENDER_BREAKPOINTS_FEATURE: boolean;
+declare const GRIDDO_SSG_VERBOSE_LOGS: boolean;
+declare const GRIDDO_SEARCH_FEATURE: boolean;
+declare const GRIDDO_ASSET_PREFIX: string | undefined;
+declare const GRIDDO_REACT_APP_INSTANCE: string | undefined;
+declare const GRIDDO_AI_EMBEDDINGS: boolean;
+declare const GRIDDO_VERBOSE_LOGS: boolean;
+declare const GRIDDO_ALERT_FEATURE: boolean;
+declare const GRIDDO_API_MAX_RESPONSE_SIZE: number;
+declare const GRIDDO_SSG_MAX_PAGE_SIZE: number;
+declare const GRIDDO_INIT_LIFECYCLE_MAX_ATTEMPTS: number;
+declare const GRIDDO_CLEAN_LIFECYCLE_MAX_ATTEMPTS: number;
+declare const GRIDDO_CLOSE_LIFECYCLE_MAX_ATTEMPTS: number;
+declare const GRIDDO_PREPARE_LIFECYCLE_MAX_ATTEMPTS: number;
+declare const GRIDDO_RESTORE_LIFECYCLE_MAX_ATTEMPTS: number;
+declare const GRIDDO_DATA_LIFECYCLE_MAX_ATTEMPTS: number;
+declare const GRIDDO_SSG_LIFECYCLE_MAX_ATTEMPTS: number;
+declare const GRIDDO_RELOCATION_LIFECYCLE_MAX_ATTEMPTS: number;
+declare const GRIDDO_META_LIFECYCLE_MAX_ATTEMPTS: number;
+declare const GRIDDO_ARCHIVE_LIFECYCLE_MAX_ATTEMPTS: number;
+declare const GRIDDO_FIXTURES_DOMAIN_NAMES: string | undefined;
+declare const GRIDDO_FIXTURES_SITE_NAMES: string | undefined;
+export { GRIDDO_AI_EMBEDDINGS, GRIDDO_ALERT_FEATURE, GRIDDO_API_CONCURRENCY_COUNT, GRIDDO_API_MAX_RESPONSE_SIZE, GRIDDO_API_URL, GRIDDO_ARCHIVE_LIFECYCLE_MAX_ATTEMPTS, GRIDDO_ASSET_PREFIX, GRIDDO_BOT_PASSWORD, GRIDDO_BOT_USER, GRIDDO_BUILD_LOGS, GRIDDO_CLEAN_LIFECYCLE_MAX_ATTEMPTS, GRIDDO_CLOSE_LIFECYCLE_MAX_ATTEMPTS, GRIDDO_DATA_LIFECYCLE_MAX_ATTEMPTS, GRIDDO_DEBUG_LOGS, GRIDDO_FIXTURES_DOMAIN_NAMES, GRIDDO_FIXTURES_SITE_NAMES, GRIDDO_INIT_LIFECYCLE_MAX_ATTEMPTS, GRIDDO_META_LIFECYCLE_MAX_ATTEMPTS, GRIDDO_PREPARE_LIFECYCLE_MAX_ATTEMPTS, GRIDDO_PUBLIC_API_URL, GRIDDO_REACT_APP_INSTANCE, GRIDDO_RELOCATION_LIFECYCLE_MAX_ATTEMPTS, GRIDDO_RENDER_ALL_SITES, GRIDDO_RENDER_BREAKPOINTS_FEATURE, GRIDDO_RENDER_PAGES, GRIDDO_RENDER_SITE, GRIDDO_RESTORE_LIFECYCLE_MAX_ATTEMPTS, GRIDDO_SEARCH_FEATURE, GRIDDO_SKIP_BUILD_CHECKS, GRIDDO_SSG_LIFECYCLE_MAX_ATTEMPTS, GRIDDO_SSG_MAX_PAGE_SIZE, GRIDDO_SSG_VERBOSE_LOGS, GRIDDO_VERBOSE_LOGS, };

package/build/constants/index.d.ts

@@ -0,0 +1,57 @@
+import type { LifeCyclesNames } from "../types/global";
+declare const endpoints: {
+    ALERT: string;
+    AI_EMBEDDINGS: string;
+    BUILD_END: string[];
+    BUILD_START: string[];
+    DOMAINS: string;
+    GET_ALL: string;
+    GET_PAGE: string;
+    GET_PAGES: string[];
+    GET_REFERENCE_FIELD_DATA: string[];
+    GET_SITEMAP: string[];
+    INFO: string[];
+    LANGUAGES: string[];
+    LOGIN: string;
+    RESET_RENDER: string;
+    ROBOTS: string;
+    SEARCH: string;
+    SETTINGS: string;
+    SOCIALS: string[];
+};
+declare const envs: {
+    GRIDDO_AI_EMBEDDINGS: boolean;
+    GRIDDO_ALERT_FEATURE: boolean;
+    GRIDDO_API_CONCURRENCY_COUNT: number;
+    GRIDDO_API_MAX_RESPONSE_SIZE: number;
+    GRIDDO_API_URL: string | undefined;
+    GRIDDO_ARCHIVE_LIFECYCLE_MAX_ATTEMPTS: number;
+    GRIDDO_ASSET_PREFIX: string | undefined;
+    GRIDDO_BOT_PASSWORD: string | undefined;
+    GRIDDO_BOT_USER: string | undefined;
+    GRIDDO_BUILD_LOGS: boolean;
+    GRIDDO_CLEAN_LIFECYCLE_MAX_ATTEMPTS: number;
+    GRIDDO_CLOSE_LIFECYCLE_MAX_ATTEMPTS: number;
+    GRIDDO_DATA_LIFECYCLE_MAX_ATTEMPTS: number;
+    GRIDDO_DEBUG_LOGS: boolean;
+    GRIDDO_FIXTURES_DOMAIN_NAMES: string | undefined;
+    GRIDDO_FIXTURES_SITE_NAMES: string | undefined;
+    GRIDDO_META_LIFECYCLE_MAX_ATTEMPTS: number;
+    GRIDDO_PREPARE_LIFECYCLE_MAX_ATTEMPTS: number;
+    GRIDDO_PUBLIC_API_URL: string | undefined;
+    GRIDDO_REACT_APP_INSTANCE: string | undefined;
+    GRIDDO_RELOCATION_LIFECYCLE_MAX_ATTEMPTS: number;
+    GRIDDO_RENDER_ALL_SITES: boolean;
+    GRIDDO_RENDER_BREAKPOINTS_FEATURE: boolean;
+    GRIDDO_RENDER_PAGES: number[];
+    GRIDDO_RENDER_SITE: number;
+    GRIDDO_RESTORE_LIFECYCLE_MAX_ATTEMPTS: number;
+    GRIDDO_SEARCH_FEATURE: boolean;
+    GRIDDO_SKIP_BUILD_CHECKS: boolean;
+    GRIDDO_SSG_LIFECYCLE_MAX_ATTEMPTS: number;
+    GRIDDO_SSG_MAX_PAGE_SIZE: number;
+    GRIDDO_SSG_VERBOSE_LOGS: boolean;
+    GRIDDO_VERBOSE_LOGS: boolean;
+};
+declare const lifeCycleNames: Record<LifeCyclesNames, LifeCyclesNames>;
+export { endpoints, envs, lifeCycleNames };